apparmor_support.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-support">
 <title>Support</title>
 <info>
      <meta name="description">Configure your system with YaST tools to ensure optimal performance, troubleshoot common issues and effectively manage AppArmor</meta>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
        <dm:bugtracker>
          </dm:bugtracker>
      </dm:docmanager>
    <revhistory xml:id="rh-cha-apparmor-support">
   <revision>
     <date>2026-04-09</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
    <para>
  This chapter outlines maintenance-related tasks. Learn how to update
  &aareg; and get a list of available man pages providing basic help for
  using the command line tools provided by &aa;. Use the troubleshooting
  section to learn about some common problems encountered with &aa; and
  their solutions. Report defects or enhancement requests for &aa;
  following the instructions in this chapter.
 </para>
 <sect1 xml:id="sec-apparmor-support-updating">
  <title>Updating &aa; Online</title>

  <para>
   Updates for &aa; packages are provided in the same way as any other
   update for &productname;. Retrieve and apply them exactly like for any
   other package that ships as part of &productname;.
  </para>
 </sect1>
 <sect1 xml:id="sec-apparmor-support-man">
  <title>Using the Man Pages</title>

  <para>
   There are man pages available for your use. In a terminal, enter
   <command>man apparmor</command> to open the &aa; man page. Man pages
   are distributed in sections numbered 1 through 8. Each section is
   specific to a category of documentation:
  </para>

  <table>
   <title>Man Pages: Sections and Categories</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>
       <para>
        Section
       </para>
      </entry>
      <entry>
       <para>
        Category
       </para>
      </entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <para>
        1
       </para>
      </entry>
      <entry>
       <para>
        User commands
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        2
       </para>
      </entry>
      <entry>
       <para>
        System calls
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        3
       </para>
      </entry>
      <entry>
       <para>
        Library functions
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        4
       </para>
      </entry>
      <entry>
       <para>
        Device driver information
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        5
       </para>
      </entry>
      <entry>
       <para>
        Configuration file formats
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        6
       </para>
      </entry>
      <entry>
       <para>
        Games
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        7
       </para>
      </entry>
      <entry>
       <para>
        High level concepts
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        8
       </para>
      </entry>
      <entry>
       <para>
        Administrator commands
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   The section numbers are used to distinguish man pages from each other.
   For example, <systemitem>exit(2)</systemitem> describes the exit system
   call, while <systemitem>exit(3)</systemitem> describes the exit C library
   function.
  </para>

  <para>
   The &aa; man pages are:
  </para>

  <itemizedlist mark="bullet" spacing="normal">
   <listitem>
    <para>
     <systemitem>aa-audit(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-autodep(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-complain(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-decode(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-disable(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-easyprof(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-enforce(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-enxec(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-genprof(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-logprof(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-notify(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-status(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa-unconfined(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>aa_change_hat(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>logprof.conf(5)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>apparmor.d(5)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>apparmor.vim(5)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>apparmor(7)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>apparmor_parser(8)</systemitem>
    </para>
   </listitem>
   <listitem>
    <para>
     <systemitem>apparmor_status(8)</systemitem>
    </para>
   </listitem>
  </itemizedlist>
 </sect1>
 <sect1 xml:id="sec-apparmor-support-info">
  <title>For More Information</title>

  <para>
   Find more information about the &aa; product at:
   <link xlink:href="http://wiki.apparmor.net"/>. Find the product
   documentation for &aa; in the installed system at
   <filename>/usr/share/doc/manual</filename>.
  </para>

  <para>
   There is a mailing list for &aa; that users can post to or join to
   communicate with developers. See
   <link xlink:href="https://lists.ubuntu.com/mailman/listinfo/apparmor"/>
   for details.
  </para>
 </sect1>
 <sect1 xml:id="sec-apparmor-support-trouble">
  <title>Troubleshooting</title>

  <para>
   This section lists the most common problems and error messages that may
   occur using &aa;.
  </para>

  <sect2 xml:id="sec-apparmor-support-trouble-odd">
   <title>How to React to odd Application Behavior?</title>
   <para>
    If you notice odd application behavior or any other type of application
    problem, you should first check the reject messages in the log files to
    see if &aa; is too closely constricting your application. If you
    detect reject messages that indicate that your application or service is
    too closely restricted by &aa;, update your profile to properly
    handle your use case of the application. Do this with
    <command>aa-logprof</command>
    (<xref linkend="sec-apparmor-commandline-profiling-summary-logprof"/>).
   </para>
   <para>
    If you decide to run your application or service without &aa;
    protection, remove the application's profile from
    <filename>/etc/apparmor.d</filename> or move it to another location.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-support-trouble-dirpath">
   <title>My Profiles Do not Seem to Work Anymore &hellip;</title>
   <remark>jsegitz 2014-07-16: This should maybe get it's own section "Upgrading from SLE 11" or something like that</remark>
   <para>
    If you have been using previous versions of &aa; and have updated
    your system (but kept your old set of profiles) you might notice some
    applications which seemed to work perfectly before you updated behaving
    strangely, or not working.
   </para>
   <para>
    This version of &aa; introduces a set of new features to the profile
    syntax and the &aa; tools that might cause trouble with older
    versions of the &aa; profiles. Those features are:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      File Locking
     </para>
    </listitem>
    <listitem>
     <para>
      Network Access Control
     </para>
    </listitem>
    <listitem>
     <para>
      The <literal>SYS_PTRACE</literal> Capability
     </para>
    </listitem>
    <listitem>
     <para>
      Directory Path Access
     </para>
    </listitem>
   </itemizedlist>
   <para>
    The current version of &aa; mediates file locking and introduces a
    new permission mode (<literal>k</literal>) for this. Applications
    requesting file locking permission might misbehave or fail altogether if
    confined by older profiles which do not explicitly contain permissions
    to lock files. If you suspect this being the case, check the log file
    under <filename>/var/log/audit/audit.log</filename> for entries like the
    following:
   </para>
<screen>type=AVC msg=audit(1389862802.727:13939): apparmor="DENIED" \
operation="file_lock" parent=2692 profile="/usr/bin/opera" \
name="/home/tux/.qt/.qtrc.lock" pid=28730 comm="httpd2-prefork" \
requested_mask="::k" denied_mask="::k" fsuid=30 ouid=0
</screen>
   <para>
    Update the profile using the <command>aa-logprof</command> command as
    outlined below.
   </para>
   <para>
    The new network access control syntax based on the network family and
    type specification, described in
    <xref linkend="sec-apparmor-profiles-nac"/>, might cause application
    misbehavior or even stop applications from working. If you notice a
    network-related application behaving strangely, check the log file under
    <filename>/var/log/audit/audit.log</filename> for entries like the
    following:
   </para>
<screen>type=AVC msg=audit(1389864332.233:13947): apparmor="DENIED" \
operation="socket_create" family="inet" parent=29985 profile="/bin/ping" \
sock_type="raw" pid=30251 comm="ping"
</screen>
   <para>
    This log entry means that our example application,
    <command>/bin/ping</command> in this case, failed to get &aa;'s
    permission to open a network connection. This permission needs to be
    explicitly stated to make sure that an application has network access.
    To update the profile to the new syntax, use the
    <command>aa-logprof</command> command as outlined below.
   </para>
   <para>
    The current kernel requires the <literal>SYS_PTRACE</literal>
    capability, if a process tries to access files in
    <filename>/proc/<replaceable>PID</replaceable>/fd/*</filename>. New
    profiles need an entry for the file and the capability, where old
    profiles only needed the file entry. For example:
   </para>
<screen>/proc/*/fd/**  rw,</screen>
   <para>
    in the old syntax would translate to the following rules in the new
    syntax:
   </para>
<screen>capability SYS_PTRACE,
/proc/*/fd/**  rw,</screen>
   <para>
    To update the profile to the new syntax, use the &yast; Update
    Profile Wizard or the <command>aa-logprof</command> command as outlined
    below.
   </para>
   <para>
    With this version of &aa;, a few changes have been made to the
    profile rule syntax to better distinguish directory from file access.
    Therefore, some rules matching both file and directory paths in the
    previous version might now match a file path only. This could lead to
    &aa; not being able to access a crucial directory, and thus
    trigger misbehavior of your application and various log messages. The
    following examples highlight the most important changes to the path
    syntax.
   </para>
   <para>
    Using the old syntax, the following rule would allow access to files and
    directories in <filename>/proc/net</filename>. It would allow directory
    access only to read the entries in the directory, but not give access to
    files or directories under the directory, for example
    <filename>/proc/net/dir/foo</filename> would be matched by the asterisk
    (*), but as <filename>foo</filename> is a file or directory under
    <filename>dir</filename>, it cannot be accessed.
   </para>
<screen>/proc/net/*  r,
</screen>
   <para>
    To get the same behavior using the new syntax, you need two rules
    instead of one. The first allows access to the file under
    <filename>/proc/net</filename> and the second allows access to
    directories under <filename>/proc/net</filename>. Directory access can
    only be used for listing the contents, not actually accessing files or
    directories underneath the directory.
   </para>
<screen>/proc/net/*  r,
/proc/net/*/  r,
</screen>
   <para>
    The following rule works similarly both under the old and the new
    syntax, and allows access to both files and directories under
    <filename>/proc/net</filename> (but does not allow a directory listing
    of <filename>/proc/net/</filename> itself):
   </para>
<screen>
/proc/net/**  r,
</screen>
   <para>
    To distinguish file access from directory access using the above
    expression in the new syntax, use the following two rules. The first one
    only allows to recursively access directories under
    <filename>/proc/net</filename> while the second one explicitly allows
    for recursive file access only.
   </para>
<screen>/proc/net/**/  r,
/proc/net/**[^/]  r,</screen>
   <para>
    The following rule works similarly both under the old and the new syntax
    and allows access to both files and directories beginning with
    <literal>foo</literal> under <filename>/proc/net</filename>:
   </para>
<screen>/proc/net/foo**  r,</screen>
   <para>
    To distinguish file access from directory access in the new syntax and
    use the <literal>**</literal> globbing pattern, use the following two
    rules. The first one would have matched both files and directories in
    the old syntax, but only matches files in the new syntax because of the
    missing trailing slash. The second rule matched neither file nor
    directory in the old syntax, but matches directories only in the new
    syntax:
   </para>
<screen>/proc/net/**foo  r,
/proc/net/**foo/  r,
</screen>
   <para>
    The following rules illustrate how the use of the <literal>?</literal>
    globbing pattern has changed. In the old syntax, the first rule would
    have matched both files and directories (four characters, last character
    could be any but a slash). In the new syntax, it matches only files
    (trailing slash is missing). The second rule would match nothing in the
    old profile syntax, but matches directories only in the new syntax. The
    last rule matches explicitly matches a file called
    <filename>bar</filename> under <filename>/proc/net/foo?</filename>.
    Using the old syntax, this rule would have applied to both files and
    directories:
   </para>
<screen>/proc/net/foo?  r,
/proc/net/foo?/  r,
/proc/net/foo?/bar  r,
</screen>
   <para>
    To find and resolve issues related to syntax changes, take some time
    after the update to check the profiles you want to keep and proceed as
    follows for each application you kept the profile for:
   </para>
   <procedure>
    <step>
     <para>
      Put the application's profile into complain mode:
     </para>
<screen><command>aa-complain</command> <option><replaceable>/path/to/application</replaceable></option></screen>
     <para>
      Log entries are made for any actions violating the current profile,
      but the profile is not enforced and the application's behavior not
      restricted.
     </para>
    </step>
    <step>
     <para>
      Run the application covering all the tasks you need this application
      to be able to perform.
     </para>
    </step>
    <step>
     <para>
      Update the profile according to the log entries made while running the
      application:
     </para>
<screen><command>aa-logprof</command> <option><replaceable>/path/to/application</replaceable></option></screen>
    </step>
    <step>
     <para>
      Put the resulting profile back into enforce mode:
     </para>
<screen><command>aa-enforce</command> <option><replaceable>/path/to/application</replaceable></option></screen>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sec-apparmor-support-trouble-apache">
   <title>Resolving Issues with Apache</title>
   <para>
    After installing additional Apache modules (like
    <literal>apache2-mod_apparmor</literal>) or making configuration changes
    to Apache, profile Apache again to find out if additional rules need to
    be added to the profile. If you do not profile Apache again, it could be
    unable to start properly or be unable to serve Web pages.
   </para>
  </sect2>

<!-- fs 2011-11-09
     (reporting is not available in 12.1 (aa-eventd isn't maintained upstream,
      and doesn't understand the (not-so-)new audit.log format))

  <sect2 id="sec-apparmor-support-trouble-report">
   <title>Why are the Reports not Sent by E-Mail?</title>
   <para>
    When the reporting feature generates an HTML or CSV file that exceeds
    the default size, the file is not sent. Mail servers have a default hard
    limit for e-mail size. This limitation can impede &aa;'s ability to send
    e-mails that are generated for reporting purposes. If your mail is not
    arriving, this could be why. Consider the mail size limits and check the
    archives if e-mails have not been received.
   </para>
  </sect2>

-->

  <sect2 xml:id="sec-apparmor-support-trouble-ex">
   <title>How to Exclude Certain Profiles from the List of Profiles Used?</title>
   <para>
    Run <command>aa-disable</command>
    <option><replaceable>PROGRAMNAME</replaceable></option> to disable the
    profile for <replaceable>PROGRAMNAME</replaceable>. This command creates
    a symbolic link to the profile in
    <filename>/etc/apparmor.d/disable/</filename>. To reactivate
    the profile, delete the link, and run <command>systemctl reload
    apparmor</command>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-support-trouble-remote">
   <title>Can I Manage Profiles for Applications not Installed on my System?</title>
   <para>
    Managing profiles with &aa; requires you to have access to the log of
    the system on which the application is running. So you do not need to
    run the application on your profile build host as long as you have
    access to the machine that runs the application. You can run the
    application on one system, transfer the logs
    (<filename>/var/log/audit.log</filename> or, if
    <filename>audit</filename> is not installed, <command>journalctl | grep
    -i apparmor &gt; path_to_logfile</command>) to your profile build host
    and run <command>aa-logprof -f</command>
    <replaceable>PATH_TO_LOGFILE</replaceable>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-support-trouble-syntax">
   <title>How to Spot and fix &aa; Syntax Errors?</title>
   <para>
    Manually editing &aa; profiles can introduce syntax errors. If you
    attempt to start or restart &aa; with syntax errors in your profiles,
    error results are shown. This example shows the syntax of the entire
    parser error.
   </para>
<screen>
localhost:~ # rcapparmor start
Loading AppArmor profiles AppArmor parser error in /etc/apparmor.d/usr.sbin.squid at line 410: syntax error, unexpected TOK_ID, expecting TOK_MODE
 Profile /etc/apparmor.d/usr.sbin.squid failed to load
</screen>
   <para>
    Using the &aa; &yast; tools, a graphical error message indicates
    which profile contained the error and requests you to fix it.
   </para>
   <informalfigure>
    <mediaobject>
     <textobject role="description">
      <phrase>Fixing syntax errors</phrase>
     </textobject>
     <imageobject role="fo">
      <imagedata fileref="aa_syncheck.png" width="60%"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="aa_syncheck.png" width="60%"/>
     </imageobject>
    </mediaobject>
   </informalfigure>
   <para>
    To fix a syntax error, log in to a terminal window as &rootuser;,
    open the profile, and correct the syntax. Reload the profile set with
    <command>systemctl reload apparmor</command>.
   </para>
   <tip>
    <title>&aa; Syntax Highlighting in <literal>vi</literal></title>
    <para>
     The editor <literal>vi</literal> on &productname; supports syntax
     highlighting for &aa; profiles. Lines containing syntax errors will
     be displayed with a red background.
    </para>
   </tip>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-support-bugs">
  <title>Reporting Bugs for &aa;</title>

  <para>
   The developers of &aa; are eager to deliver products of the highest
   quality. Your feedback and your bug reports help us keep the quality
   high. Whenever you encounter a bug in &aa;, file a bug report against
   this product:
  </para>

  <procedure>
   <step>
    <para>
     Use your Web browser to go to <link os="sles;sled" xlink:href="http://bugzilla.suse.com/"/><link os="osuse" xlink:href="http://bugzilla.opensuse.org/"/> and click <guimenu>Log
     In</guimenu>.
    </para>
   </step>
   <step>
    <para>
     Enter the account data of your &suse; account and click
     <guimenu>Login</guimenu>. If you do not have a &suse; account, click
     <guimenu>Create Account</guimenu> and provide the required data.
    </para>
   </step>
   <step>
    <para>
     If your problem has already been reported, check this bug report and
     add extra information to it, if necessary.
    </para>
   </step>
   <step>
    <para>
     If your problem has not been reported yet, select
     <guimenu>New</guimenu> from the top navigation bar and proceed to the
     <guimenu>Enter Bug</guimenu> page.
    </para>
   </step>
   <step>
    <para>
     Select the product against which to file the bug. In your case, this
     would be your product's release. Click <guimenu>Submit</guimenu>.
    </para>
   </step>
   <step>
    <para>
     Select the product version, component (&aa; in this case), hardware
     platform, and severity.
    </para>
   </step>
   <step>
    <para>
     Enter a brief headline describing your problem and add a more elaborate
     description including log files. You may create attachments to your bug
     report for screenshots, log files, or test cases.
    </para>
   </step>
   <step>
    <para>
     Click <guimenu>Submit</guimenu> after you have entered all the details
     to send your report to the developers.
    </para>
   </step>
  </procedure>
 </sect1>
</chapter>