apparmor_profiles_man.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" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" role="General" xml:id="cha-apparmor-commandline">
 <title>Building profiles from the command line</title>
 <info>
      <meta name="description" its:translate="yes">Manage system security with AppArmor by configuring and monitoring its profiles using command-line tools</meta>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
        <dm:bugtracker>
        </dm:bugtracker>
	<dm:translation>yes</dm:translation>
      </dm:docmanager>
    <revhistory xml:id="rh-cha-apparmor-commandline">
   <revision>
     <date>2026-04-07</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
    <para>
  &aareg; provides the user the ability to use a command line interface
  rather than a graphical interface to manage and configure the system
  security. Track the status of &aa; and create, delete or modify
  &aa; profiles using the &aa; command line tools.
 </para>
 <tip>
  <title>Background information</title>
  <para>
   Before starting to manage your profiles using the &aa; command line
   tools, check out the general introduction to &aa; given in
   <xref linkend="cha-apparmor-concept"/> and
   <xref linkend="cha-apparmor-profiles"/>.
  </para>
 </tip>
 <sect1 xml:id="sec-apparmor-commandline-status">
  <title>Checking the &aa; status</title>

  <para>
   &aa; can be in any one of three states:
  </para>

  <variablelist>
   <varlistentry>
    <term>Unloaded</term>
    <listitem>
     <para>
      &aa; is not activated in the kernel.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Running</term>
    <listitem>
     <para>
      &aa; is activated in the kernel and is enforcing &aa; program
      policies.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Stopped</term>
    <listitem>
     <para>
      &aa; is activated in the kernel, but no policies are enforced.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Detect the state of &aa; by inspecting
   <filename>/sys/kernel/security/apparmor/profiles</filename>. If
   <command>cat /sys/kernel/security/apparmor/profiles</command> reports a
   list of profiles, &aa; is running. If it is empty and returns nothing,
   &aa; is stopped. If the file does not exist, &aa; is unloaded.
  </para>

  <para>
   Manage &aa; with <command>systemctl</command>. It lets you perform the
   following operations:
  </para>

  <variablelist>
   <varlistentry>
    <term><command>sudo systemctl start apparmor</command>
    </term>
    <listitem>
     <para>
      Behavior depends on the state of &aa;. If it is not activated,
      <option>start</option> activates and starts it, putting it in the
      running state. If it is stopped, <option>start</option> causes the
      re-scan of &aa; profiles found in
      <filename>/etc/apparmor.d</filename> and puts &aa; in the running
      state. If &aa; is already running, <option>start</option> reports a
      warning and takes no action.
     </para>
     <note>
      <title>Already running processes</title>
      <para>
       Already running processes need to be restarted to apply the &aa;
       profiles on them.
      </para>
     </note>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>sudo systemctl stop apparmor</command>
    </term>
    <listitem>
     <para>
      Stops &aa; if it is running by removing all profiles from kernel
      memory, effectively disabling all access controls, and putting &aa;
      into the stopped state. If the &aa; is already stopped,
      <option>stop</option> tries to unload the profiles again, but nothing
      happens.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>sudo systemctl reload apparmor</command>
    </term>
    <listitem>
     <para>
      Causes the &aa; module to re-scan the profiles in
      <filename>/etc/apparmor.d</filename> without unconfining running
      <remark>sknorr, 2014-08-26: "unconfining?" Sounds terrible. Would
       "freeing" be an option?
       tbazant, 2014-09-08: No, it's a used term, related to 'unconfined' state
       </remark>
      processes. Freshly created profiles are enforced and recently deleted
      ones are removed from the <filename>/etc/apparmor.d</filename>
      directory.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
</sect1>
 <sect1 xml:id="sec-apparmor-commandline-build">
  <title>Building &aa; profiles</title>

  <para>
   The &aa; module profile definitions are stored in the
   <filename>/etc/apparmor.d</filename> directory as plain text files. For a
   detailed description of the syntax of these files, refer to
   <xref linkend="cha-apparmor-profiles"/>.
  </para>

  <para>
   All files in the <filename>/etc/apparmor.d</filename> directory are
   interpreted as profiles and are loaded as such. Renaming files in that
   directory is not an effective way of preventing profiles from being
   loaded. You must remove profiles from this directory to prevent them from
   being read and evaluated effectively, or call
   <command>aa-disable</command> on the profile, which creates a
   symbolic link in <filename>/etc/apparmor.d/disabled/</filename>.
  </para>

  <para>
   You can use a text editor, such as <command>vi</command>, to access and
   make changes to these profiles. The following sections contain detailed
   steps for building profiles:
  </para>

  <variablelist>
   <varlistentry>
    <term>Adding or creating &aa; profiles</term>
    <listitem>
     <para>
      Refer to <xref linkend="sec-apparmor-commandline-add"/>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Editing &aa; profiles</term>
    <listitem>
     <para>
      Refer to <xref linkend="sec-apparmor-commandline-edit"/>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Deleting &aa; profiles</term>
    <listitem>
     <para>
      Refer to
      <xref linkend="sec-apparmor-commandline-del"/>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

<!-- Code 10 doesn't have apparmor.vim. Maybe next release ...
   <para>
   Use vim to view and edit your profile by typing <command>vim</command> in a
   terminal window. To enable syntax highlighting when you edit an &aa;
  profile in
   vim, use the commands <command>:syntax on</command> then <command>:set
   syntax=apparmor</command>. For more information about vim and syntax
   coloring, refer to <xref
   linkend="sec-apparmor-commandline-profiling-summary-vim"/>.
  </para>
   -->
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-add">
  <title>Adding or creating an &aa; profile</title>

  <para>
   To add or create an &aa; profile for an application, you can use a
   systemic or stand-alone profiling method, depending on your needs. Learn
   more about these two approaches in
   <xref linkend="sec-apparmor-commandline-profiling"/>.
  </para>
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-edit">
  <title>Editing an &aa; profile</title>

  <para>
   The following steps describe the procedure for editing an &aa;
   profile:
  </para>

  <procedure>
   <step>
    <para>
     If you are not currently logged in as &rootuser;, enter
     <command>su</command> in a terminal window.
    </para>
   </step>
   <step>
    <para>
     Enter the &rootuser; password when prompted.
    </para>
   </step>
   <step>
    <para>
     Go to the profile directory with <command>cd
     /etc/apparmor.d/</command>.
    </para>
   </step>
   <step>
    <para>
     Enter <command>ls</command> to view all profiles currently installed.
    </para>
   </step>
   <step>
    <para>
     Open the profile to edit in a text editor, such as vim.
    </para>
   </step>
   <step>
    <para>
     Make the necessary changes, then save the profile.
    </para>
   </step>
   <step>
    <para>
     Restart &aa; by entering <command>systemctl reload
     apparmor</command> in a terminal window.
    </para>
   </step>
  </procedure>
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-unload">
  <title>Unloading unknown &aa; profiles</title>
  <warning>
   <title>Danger of unloading wanted profiles</title>
   <para>
    <command>aa-remove-unknown</command> unloads all profiles that
    are not stored in <filename>/etc/apparmor.d</filename>, for example
    automatically generated LXD profiles. This may compromise the
    security of the system. Use the <option>-n</option> parameter to
    list all profiles that are unloaded.
   </para>
  </warning>
  <para>
   To unload all &aa; profiles that are no longer in
   <filename>/etc/apparmor.d/</filename>, run:
  </para>
  <screen>&prompt.sudo;<command>aa-remove-unknown</command></screen>
  <para>
   You can print a list of profiles that are removed:
  </para>
  <screen>&prompt.sudo;<command>aa-remove-unknown -n</command></screen>
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-del">
  <title>Deleting an &aa; profile</title>
  <para>
   The following steps describe the procedure for deleting an &aa;
   profile.
  </para>
  <procedure>
   <step>
    <para>
     Remove the &aa; definition from the kernel:
    </para>
    <screen>&prompt.sudo;<command>apparmor_parser -R /etc/apparmor.d/<replaceable>PROFILE</replaceable></command></screen>
   </step>
   <step>
    <para>
     Remove the definition file:
    </para>
    <screen>&prompt.sudo;<command>rm /etc/apparmor.d/<replaceable>PROFILE</replaceable></command>
    &prompt.sudo;<command>rm /var/lib/apparmor/cache/<replaceable>PROFILE</replaceable></command></screen>
   </step>
  </procedure>
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-profiling">
  <title>Two methods of profiling</title>

  <para>
   Given the syntax for &aa; profiles in
   <xref linkend="cha-apparmor-profiles"/>, you
   could create profiles without using the tools. However, the effort
   involved would be substantial. To avoid such a situation, use the &aa;
   tools to automate the creation and refinement of profiles.
  </para>

  <para>
   There are two ways to approach &aa; profile creation. Tools are
   available for both methods.
  </para>

  <variablelist>
   <varlistentry>
    <term>Stand-alone profiling</term>
    <listitem>
     <para>
      A method suitable for profiling small applications that have a finite
      runtime, such as user client applications like mail clients. For more
      information, refer to
      <xref linkend="sec-apparmor-commandline-profiling-stand-alone"/>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Systemic profiling</term>
    <listitem>
     <para>
      A method suitable for profiling many programs at once
      and for profiling applications that may run for days, weeks or
      continuously across reboots, such as network server applications like
      Web servers and mail servers. For more information, refer to
      <xref linkend="sec-apparmor-commandline-profiling-systemic"/>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Automated profile development becomes more manageable with the &aa;
   tools:
  </para>

  <procedure>
   <step>
    <para>
     Decide which profiling method suits your needs.
    </para>
   </step>
   <step>
    <para>
     Perform a static analysis. Run either <command>aa-genprof</command> or
     <command>aa-autodep</command>, depending on the profiling method
     chosen.
    </para>
   </step>
   <step>
    <para>
     Enable dynamic learning. Activate learning mode for all profiled
     programs.
    </para>
   </step>
  </procedure>

  <sect2 xml:id="sec-apparmor-commandline-profiling-stand-alone">
   <title>Stand-alone profiling</title>
   <para>
    Stand-alone profile generation and improvement is managed by a program
    called <command>aa-genprof</command>. This method is easy because
    <command>aa-genprof</command> takes care of everything, but is limited
    because it requires <command>aa-genprof</command> to run for the entire
    duration of the test run of your program (you cannot reboot the machine
    while you are still developing your profile).
   </para>
   <para>
    To use <command>aa-genprof</command> for the stand-alone method of
    profiling, refer to
    <xref linkend="sec-apparmor-commandline-profiling-summary-genprof"/>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-commandline-profiling-systemic">
   <title>Systemic profiling</title>
   <para>
    This method is called <emphasis>systemic profiling</emphasis> because it
    updates all the profiles on the system at once, rather than focusing
    on the one or few targeted by <command>aa-genprof</command> or
    stand-alone profiling. With systemic profiling, profile construction and
    improvement are less automated, but more flexible. This method
    is suitable for profiling long-running applications whose behavior
    continues after rebooting, or many programs at once.
   </para>
   <para>
    Build an &aa; profile for a group of applications as follows:
   </para>
   <procedure>
    <step>
     <para>
      Create profiles for the individual programs that make up your
      application.
     </para>
     <para>
      Although this approach is systemic, &aa; only monitors those
      programs with profiles and their children. To get &aa; to consider
      a program, you must at least have <command>aa-autodep</command> create
      an approximate profile for it. To create this approximate profile,
      refer to
      <xref linkend="sec-apparmor-commandline-profiling-summary-autodep"/>.
     </para>
    </step>
    <step>
     <para>
      Put relevant profiles into learning or complain mode.
     </para>
     <para>
      Activate learning or complain mode for all profiled programs by
      entering
     </para>
<screen>&prompt.sudo;aa-complain /etc/apparmor.d/*</screen>
     <para>
      in a terminal window while logged in as &rootuser;. This
      functionality is also available through the &yast; Profile Mode
      module, described in
      <xref linkend="sec-apparmor-yast-manage-profmodes"/>.
     </para>
     <para>
      When in learning mode, access requests are not blocked, even if the
      profile dictates that they should be. This enables you to run through
      several tests (as shown in
      <xref linkend="st-apparmor-commandline-profiling-systemic-exec"/>) and
      learn the access needs of the program so it runs properly. With this
      information, you can decide how secure to make the profile.
     </para>
     <para>
      Refer to
      <xref linkend="sec-apparmor-commandline-profiling-summary-complain"/>
      for more detailed instructions for using learning or complain mode.
     </para>
    </step>
    <step xml:id="st-apparmor-commandline-profiling-systemic-exec">
     <para>
      Exercise your application.
     </para>
     <para>
      Run your application and exercise its functionality. How much to
      exercise the program is up to you, but you need the program to access
      each file representing its access needs. Because the execution is not
      being supervised by <command>aa-genprof</command>, this step can go on
      for days or weeks and can span complete system reboots.
     </para>
    </step>
    <step xml:id="st-apparmor-commandline-profiling-systemic-log">
     <para>
      Analyze the log.
     </para>
     <para>
      In systemic profiling, run <command>aa-logprof</command> directly
      instead of letting <command>aa-genprof</command> run it (as in
      stand-alone profiling). The general form of
      <command>aa-logprof</command> is:
     </para>
<screen>&prompt.sudo;aa-logprof [ -d <replaceable>/path/to/profiles</replaceable> ] [ -f <replaceable>/path/to/logfile</replaceable> ]</screen>
     <para>
      Refer to
      <xref linkend="sec-apparmor-commandline-profiling-summary-logprof"/>
      for more information about using <command>aa-logprof</command>.
     </para>
    </step>
    <step>
     <para>
      Repeat
      <xref linkend="st-apparmor-commandline-profiling-systemic-exec"/> and
      <xref linkend="st-apparmor-commandline-profiling-systemic-log"/>.
     </para>
     <para>
      This generates optimal profiles. An iterative approach captures
      smaller data sets that can be trained and reloaded into the policy
      engine. Subsequent iterations generate fewer messages and run faster.
     </para>
    </step>
    <step>
     <para>
      Edit the profiles.
     </para>
     <para>
      You should review the profiles that have been generated. You
      can open and edit the profiles in
      <filename>/etc/apparmor.d/</filename> using a text editor.
     </para>
    </step>
    <step>
     <para>
      Return to enforce mode.
     </para>
     <para>
      This is when the system goes back to enforcing the rules of the
      profiles, not only logging information. This can be done manually by
      removing the <literal>flags=(complain)</literal> text from the
<!-- could also be a symbolic link in /etc/apparmor.d/force-complain/ -->
      profiles or automatically by using the <command>aa-enforce</command>
      command, which works identically to the <command>aa-complain</command>
      command, except it sets the profiles to enforce mode. This
      functionality is also available through the &yast; Profile Mode
      module, described in
      <xref linkend="sec-apparmor-yast-manage-profmodes"/>.
     </para>
     <para>
      To ensure that all profiles are taken out of complain mode and put
      into enforce mode, enter <command>aa-enforce
      /etc/apparmor.d/*</command>.
     </para>
    </step>
    <step>
     <para>
      Re-scan all profiles.
     </para>
     <para>
      To have &aa; re-scan all the profiles and change the enforcement
      mode in the kernel, enter <command>systemctl reload
      apparmor</command>.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sec-apparmor-commandline-profiling-summary">
   <title>Summary of profiling tools</title>
   <para>
    All of the &aa; profiling utilities are provided by the
    <systemitem>apparmor-utils</systemitem> RPM package and are stored in
    <filename>/usr/sbin</filename>. Each tool has a different purpose.
   </para>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-autodep">
    <title>aa-autodep&mdash;creating approximate profiles</title>
    <para>
     This creates an approximate profile for the program or application
     selected. You can generate approximate profiles for binary executables
     and interpreted script programs. The resulting profile is called
     <quote>approximate</quote> because it does not necessarily contain all
     of the profile entries that the program needs to be properly confined
     by &aa;. The minimum <command>aa-autodep</command> approximate
     profile has, at minimum, a base include directive, which contains basic
     profile entries needed by most programs. For certain types of programs,
     <command>aa-autodep</command> generates a more expanded profile. The
     profile is generated by recursively calling <command>ldd(1)</command>
     on the executables listed on the command line.
    </para>
    <para>
     To generate an approximate profile, use the
     <command>aa-autodep</command> program. The program argument can be
     either the simple name of the program, which
     <command>aa-autodep</command> finds by searching your shell's path
     variable, or it can be a fully qualified path. The program itself can
     be of any type (ELF binary, shell script, Perl script, etc.).
     <command>aa-autodep</command> generates an approximate profile to
     improve through the dynamic profiling that follows.
    </para>
    <para>
     The resulting approximate profile is written to the
     <filename>/etc/apparmor.d</filename> directory using the &aa;
     profile naming convention of naming the profile after the absolute path
     of the program, replacing the forward slash (<literal>/</literal>)
     characters in the path with period (<literal>.</literal>) characters.
     The general syntax of <command>aa-autodep</command> is to enter the
     following in a terminal window:
    </para>
<screen>&prompt.sudo;aa-autodep [ -d <replaceable>/PATH/TO/PROFILES</replaceable> ] [<replaceable>PROGRAM1</replaceable> <replaceable>PROGRAM2</replaceable>...]</screen>
    <para>
     If you do not enter the program name or names, you are prompted for
     them. <replaceable>/path/to/profiles</replaceable> overrides the
     default location of <filename>/etc/apparmor.d</filename>, should you
     keep profiles in a location other than the default.
    </para>
    <para>
     To begin profiling, you must create profiles for each main executable
     service that is part of your application (anything that might start
     without being a child of another program that already has a profile).
     Finding all such programs depends on the application in question. Here
     are several strategies for finding such programs:
    </para>
    <variablelist>
     <varlistentry>
      <term>Directories</term>
      <listitem>
       <para>
        If all the programs to profile are in one directory and there are no
        other programs in that directory, the simple command
        <command>aa-autodep</command>
        <replaceable>/path/to/your/programs/*</replaceable> creates basic
        profiles for all programs in that directory.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>pstree -p</term>
      <listitem>
       <para>
        You can run your application and use the standard Linux
        <command>pstree</command> command to find all processes running.
        Then manually hunt down the location of these programs and run the
        <command>aa-autodep</command> for each one. If the programs are in
        your path, <command>aa-autodep</command> finds them for you. If they
        are not in your path, the standard Linux command
        <command>find</command> might be helpful in finding your programs.
        Execute <command>find / -name '</command>
        <replaceable>MY_APPLICATION</replaceable>' -print to determine an
        application's path (<replaceable>MY_APPLICATION</replaceable> being
        an example application). You may use wild cards if appropriate.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-complain">
    <title>aa-complain&mdash;entering complain or learning mode</title>
    <para>
     The complain or learning mode tool (<command>aa-complain</command>)
     detects violations of &aa; profile rules, such as the profiled
     program accessing files not permitted by the profile. The violations
     are permitted, but also logged. To improve the profile, turn complain
     mode on, run the program through a suite of tests to generate log
     events that characterize the program's access needs, then postprocess
     the log with the &aa; tools to transform log events into improved
     profiles.
    </para>
    <para>
     Manually activating complain mode (using the command line) adds a flag
     to the top of the profile so that <literal>/bin/foo</literal> becomes
     <literal>/bin/foo flags=(complain)</literal>. To use complain mode,
<!-- or create a symbolic link in force-complain -->
     open a terminal window and enter one of the following lines as
     &rootuser;:
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       If the example program (<replaceable>PROGRAM1</replaceable>) is in
       your path, use:
      </para>
<screen>&prompt.sudo;aa-complain [<replaceable>PROGRAM1</replaceable> <replaceable>PROGRAM2</replaceable> ...]</screen>
     </listitem>
     <listitem>
      <para>
       If the program is not in your path, specify the entire path as
       follows:
      </para>
<screen>&prompt.sudo;aa-complain /sbin/<replaceable>PROGRAM1</replaceable></screen>
     </listitem>
     <listitem>
      <para>
       If the profiles are not in <filename>/etc/apparmor.d</filename>, use
       the following to override the default location:
      </para>
<screen>&prompt.sudo;aa-complain <replaceable>/path/to/profiles/</replaceable><replaceable>PROGRAM1</replaceable></screen>
     </listitem>
     <listitem>
      <para>
       Specify the profile for <replaceable>/sbin/program1</replaceable> as
       follows:
      </para>
<screen>&prompt.sudo;aa-complain /etc/apparmor.d/sbin.<replaceable>PROGRAM1</replaceable></screen>
     </listitem>
    </itemizedlist>
    <para>
     Each of the above commands activates the complain mode for the profiles
     or programs listed. If the program name does not include its entire
     path, <command>aa-complain</command> searches <envar>$PATH</envar> for
     the program. For example, <command>aa-complain /usr/sbin/*</command>
     finds profiles associated with all the programs in
     <filename>/usr/sbin</filename> and puts them into complain mode.
     <command>aa-complain /etc/apparmor.d/*</command> puts all the
     profiles in <filename>/etc/apparmor.d</filename> into complain mode.
    </para>
    <tip>
     <title>Toggling profile mode with &yast;</title>
     <para>
      &yast; offers a graphical front-end for toggling complain and
      enforce mode. See <xref linkend="sec-apparmor-yast-manage-profmodes"/>
      for information.
     </para>
    </tip>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-decode">
    <title>aa-decode&mdash;decoding hex-encoded strings in &aa; log files</title>
    <para>
     <command>aa-decode</command> decodes hex-encoded strings in the
     &aa; log output. It can also process the audit log on standard
     input, convert any hex-encoded &aa; log entries, and display them on
     standard output.
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-disable">
    <title>aa-disable&mdash;disabling an &aa; security profile</title>
    <para>
     Use <command>aa-disable</command> to disable the enforcement mode for
     one or more &aa; profiles. This command unloads the profile from
     the kernel and prevents the profile from being loaded on &aa;
     start-up. Use <command>aa-enforce</command> or
     <command>aa-complain</command> utilities to change this behavior.
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-easyprof">
    <title>aa-easyprof&mdash;easy profile generation</title>
    <para>
     <command>aa-easyprof</command> provides an easy-to-use interface for
     &aa; profile generation. <command>aa-easyprof</command> supports the
     use of templates and profile groups to quickly profile an application.
     While <command>aa-easyprof</command> can help with profile generation,
     its utility is dependent on the quality of the templates, profile
     groups and abstractions used. Also, this tool may create a profile that
     is less restricted than when creating a profile manually or with
     <command>aa-genprof</command> and <command>aa-logprof</command>.
    </para>
    <para>
     For more information, see the man page of
     <command>aa-easyprof</command> (8).
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-enforce">
    <title>aa-enforce&mdash;entering enforce mode</title>
    <para>
     The enforce mode detects violations of &aa; profile rules, such as
     the profiled program accessing files not permitted by the profile. The
     violations are logged and not permitted. The default is for enforce
     mode to be enabled. To log the violations only, but still permit them,
     use complain mode.
    </para>
    <para>
     Manually activating enforce mode (using the command line) removes the
     complain flag from the top of the profile so that <literal>/bin/foo
     flags=(complain)</literal> becomes <literal>/bin/foo</literal>. To use
     enforce mode, open a terminal window and enter one of the following
     lines.
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       If the example program (<replaceable>PROGRAM1</replaceable>) is in
       your path, use:
      </para>
<screen>&prompt.sudo;aa-enforce [<replaceable>PROGRAM1</replaceable> <replaceable>PROGRAM2</replaceable> ...]</screen>
     </listitem>
     <listitem>
      <para>
       If the program is not in your path, specify the entire path, as
       follows:
      </para>
<screen>&prompt.sudo;aa-enforce /sbin/<replaceable>PROGRAM1</replaceable></screen>
     </listitem>
     <listitem>
      <para>
       If the profiles are not in
       <replaceable>/etc/apparmor.d</replaceable>, use the following to
       override the default location:
      </para>
<screen>&prompt.sudo;aa-enforce -d <replaceable>/path/to/profiles/     program1</replaceable></screen>
     </listitem>
     <listitem>
      <para>
       Specify the profile for <replaceable>/sbin/program1</replaceable> as
       follows:
      </para>
<screen>&prompt.sudo;aa-enforce /etc/apparmor.d/sbin.<replaceable>PROGRAM1</replaceable></screen>
     </listitem>
    </itemizedlist>
    <para>
     Each of the above commands activates the enforce mode for the profiles
     and programs listed.
    </para>
    <para>
     If you do not enter the program or profile names, you are prompted to
     enter one. <replaceable>/path/to/profiles</replaceable> overrides the
     default location of <filename>/etc/apparmor.d</filename>.
    </para>
    <para>
     The argument can be either a list of programs or a list of profiles. If
     the program name does not include its entire path,
     <command>aa-enforce</command> searches <envar>$PATH</envar> for the
     program.
    </para>
    <tip>
     <title>Toggling profile mode with &yast;</title>
     <para>
      &yast; offers a graphical front-end for toggling complain and
      enforce mode. See <xref linkend="sec-apparmor-yast-manage-profmodes"/>
      for information.
     </para>
    </tip>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-exec">
    <title>aa-exec&mdash;confining a program with the specified profile</title>
    <para>
     Use <command>aa-exec</command> to launch a program confined by a
     specified profile and/or profile namespace. If both a profile and
     namespace are specified, the program is confined by the profile in
     the new namespace. If only a profile namespace is specified, the
     profile name of the current confinement is used. If neither a
     profile nor namespace is specified, the command runs using the
     standard profile attachment&mdash;as if you did not use the
     <command>aa-exec</command> command.
    </para>
    <para>
     For more information on the command's options, see its manual page
     <command>man 8 aa-exec</command>.
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-genprof">
    <title>aa-genprof&mdash;generating profiles</title>
    <para>
     <command>aa-genprof</command> is &aa;'s profile generating utility.
     It runs <command>aa-autodep</command> on the specified program,
     creating an approximate profile (if a profile does not already exist
     for it), sets it to complain mode, reloads it into &aa;, marks the
     log, and prompts the user to execute the program and exercise its
     functionality. Its syntax is as follows:
    </para>
<screen>&prompt.sudo;aa-genprof [ -d <replaceable>/path/to/profiles</replaceable> ]  <replaceable>PROGRAM</replaceable></screen>
    <para>
     To create a profile for the Apache Web server program httpd2-prefork,
     do the following as &rootuser;:
    </para>
    <procedure>
     <step>
      <para>
       Enter <command>systemctl stop apache2</command>.
      </para>
     </step>
     <step>
      <para>
       Next, enter <command>aa-genprof httpd2-prefork</command>.
      </para>
      <para>
       Now <command>aa-genprof</command> does the following:
      </para>
      <orderedlist spacing="normal">
       <listitem>
        <para>
         Resolves the full path of httpd2-prefork using your shell's path
         variables. You can also specify a full path. On &productname;,
         the default full path is
         <phrase><filename>/usr/sbin/httpd2-prefork</filename></phrase>.
        </para>
       </listitem>
       <listitem>
        <para>
         Checks to see if there is an existing profile for httpd2-prefork.
         If there is one, it updates it. If not, it creates one using the
         <command>aa-autodep</command> as described in
         <xref linkend="sec-apparmor-commandline-profiling-summary"/>.
        </para>
       </listitem>
       <listitem>
        <para>
         Puts the profile for this program into learning or complain mode so
         that profile violations are logged, but are permitted to proceed. A
         log event looks like this (see
         <filename>/var/log/audit/audit.log</filename>):
        </para>
<screen>type=APPARMOR_ALLOWED msg=audit(1189682639.184:20816): \
apparmor="DENIED" operation="file_mmap" parent=2692 \
profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0</screen>
        <para>
         If you are not running the audit daemon, the &aa; events are
         logged directly to &systemd; journal (see
         <xref linkend="cha-journalctl"/>):
        </para>
<screen>Sep 13 13:20:30 K23 kernel: audit(1189682430.672:20810): \
apparmor="DENIED" operation="file_mmap" parent=2692 \
profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0</screen>
        <para>
         They also can be viewed using the <command>dmesg</command> command:
        </para>
<screen>audit(1189682430.672:20810): apparmor="DENIED" \
operation="file_mmap" parent=2692 \
profile="/usr/sbin/httpd2-prefork//HANDLING_UNTRUSTED_INPUT" \
name="/var/log/apache2/access_log-20140116" pid=28730 comm="httpd2-prefork" \
requested_mask="::r" denied_mask="::r" fsuid=30 ouid=0</screen>
       </listitem>
       <listitem>
        <para>
         Marks the log with a beginning marker of log events to consider.
         For example:
        </para>
<screen>
Sep 13 17:48:52 figwit root: GenProf: e2ff78636296f16d0b5301209a04430d</screen>
       </listitem>
      </orderedlist>
     </step>
     <step>
      <para>
       When prompted by the tool, run the application to profile in another
       terminal window and perform as many of the application functions as
       possible. Thus, the learning mode can log the files and directories
       to which the program requires access to function properly.
       For example, in a new terminal window, enter <command>systemctl start
       apache2</command>.
      </para>
     </step>
     <step>
      <para>
       Select from the following options that are available in the
       <command>aa-genprof</command> terminal window after you have executed
       the program function:
      </para>
      <itemizedlist mark="bullet" spacing="normal">
       <listitem>
        <para>
         <keycap>S</keycap> runs <command>aa-genprof</command> on the system
         log from where it was marked when <command>aa-genprof</command> was
         started and reloads the profile. If system events exist in the log,
         &aa; parses the learning mode log files. This generates a series
         of questions that you must answer to guide
         <command>aa-genprof</command> in generating the security profile.
        </para>
       </listitem>
       <listitem>
        <para>
         <keycap>F</keycap> exits the tool.
        </para>
       </listitem>
      </itemizedlist>
      <note>
       <para>
        If requests to add hats appear, proceed to
        <xref linkend="cha-apparmor-hat"/>.
       </para>
      </note>
     </step>
     <step>
      <para>
       Answer two types of questions:
      </para>
      <itemizedlist mark="bullet" spacing="normal">
       <listitem>
        <para>
         A resource is requested by a profiled program that is not in the
         profile (see
         <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-learn"/>).
        </para>
       </listitem>
       <listitem>
        <para>
         A program is executed by the profiled program and the security
         domain transition has not been defined (see
         <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-perms"/>).
        </para>
       </listitem>
      </itemizedlist>
      <para>
       Each of these categories results in a series of questions that you
       must answer to add the resource or program to the profile.
       <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-learn"/>
       and
       <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-perms"/>
       provide examples of each one. Subsequent steps describe your options
       in answering these questions.
      </para>
      <itemizedlist mark="bullet" spacing="normal">
       <listitem>
        <para>
         Dealing with execute accesses is complex. You must decide how to
         proceed with this entry regarding which execute permission type to
         grant to this entry:
        </para>
        <example xml:id="ex-apparmor-commandline-profiling-summary-genprof-learn">
         <title>Learning mode exception: controlling access to specific resources</title>
<screen>Reading log entries from /var/log/audit/audit.log.
Updating AppArmor profiles in /etc/apparmor.d.

Profile:  /usr/sbin/cupsd
Program:  cupsd
Execute:  /usr/lib/cups/daemon/cups-lpd
Severity: unknown

(I)nherit / (P)rofile / (C)hild / (N)ame / (U)nconfined / (X)ix / (D)eny / Abo(r)t / (F)inish</screen>
        </example>
        <variablelist>
         <varlistentry>
          <term>Inherit (ix)</term>
          <listitem>
           <para>
            The child inherits the parent's profile, running with the same
            access controls as the parent. 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. This mode is often used when
            the child program is a <emphasis>helper application</emphasis>,
            such as the <command>/usr/bin/mail</command> client using
            <command>less</command> as a pager.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Profile (px/px)</term>
          <listitem>
           <para>
            The child runs using its own profile, which must be loaded into
            the kernel. If the profile is not present, attempts to execute
            the child fail with permission denied. This is most useful if
            the parent program is invoking a global service, such as DNS
            lookups or sending mail with your system's MTA.
           </para>
           <para>
            Choose the <guimenu>profile with clean exec</guimenu> (Px)
            option to scrub the environment of environment variables that
            could modify execution behavior when passed to the child
            process.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Child (cx/cx)</term>
          <listitem>
           <para>
            Sets up a transition to a subprofile. It is like px/Px
            transition, except to a child profile.
           </para>
           <para>
            Choose the <guimenu>profile with clean exec</guimenu> (Cx)
            option to scrub the environment of environment variables that
            could modify execution behavior when passed to the child
            process.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Unconfined (ux/ux)</term>
          <listitem>
           <para>
            The child runs unconfined without any &aa; profile
            applied to the executed resource.
           </para>
           <para>
            Choose the <guimenu>unconfined with clean exec</guimenu> (Ux)
            option to scrub the environment of environment variables that
            could modify execution behavior when passed to the child
            process. Note that running unconfined profiles introduces a
            security vulnerability that could be used to evade &aa;. Only
            use it as a last resort.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>mmap (m)</term>
          <listitem>
           <para>
            This permission denotes that the program running under the
            profile can access the resource using the mmap system call with
            the flag <envar>PROT_EXEC</envar>. This means that the data
            mapped in it can be executed. You are prompted to include this
            permission if it is requested during a profiling run.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Deny</term>
          <listitem>
           <para>
            Adds a <literal>deny</literal> rule to the profile, and
            permanently prevents the program from accessing the specified
            directory path entries. &aa; then continues to the next
            event.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Abort</term>
          <listitem>
           <para>
            Aborts <command>aa-logprof</command>, losing all rule changes
            entered so far and leaving all profiles unmodified.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Finish</term>
          <listitem>
           <para>
            Closes <command>aa-logprof</command>, saving all rule changes
            entered so far and modifying all profiles.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </listitem>
       <listitem>
        <para>
         <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-perms"/>
         shows &aa; suggest allowing a globbing pattern
         <filename>/var/run/nscd/*</filename> for reading, then using an
         abstraction to cover common Apache-related access rules.
        </para>
        <example xml:id="ex-apparmor-commandline-profiling-summary-genprof-perms">
         <title>Learning mode exception: defining permissions for an entry</title>
<screen><?dbfo keep-together="always"?>Profile:  /usr/sbin/httpd2-prefork
Path:     /var/run/nscd/dbSz9CTr
Mode:     r
Severity: 3

  1 - /var/run/nscd/dbSz9CTr
 [2 - /var/run/nscd/*]

(A)llow / [(D)eny] / (G)lob / Glob w/(E)xt / (N)ew / Abo(r)t / (F)inish / (O)pts
Adding /var/run/nscd/* r to profile.

Profile:  /usr/sbin/httpd2-prefork
Path:     /proc/11769/attr/current
Mode:     w
Severity: 9

 [1 - #include &lt;abstractions/apache2-common&gt;]
  2 - /proc/11769/attr/current
  3 - /proc/*/attr/current

(A)llow / [(D)eny] / (G)lob / Glob w/(E)xt / (N)ew / Abo(r)t / (F)inish / (O)pts
Adding #include &lt;abstractions/apache2-common&gt; to profile.
</screen>
        </example>
        <para>
         &aa; provides one or more paths or includes. By entering the
         option number, select the desired options then proceed to the next
         step.
        </para>
        <note>
         <para>
          Not all these options are always presented in the &aa; menu.
         </para>
        </note>
        <variablelist>
         <varlistentry>
          <term><literal>#include</literal>
          </term>
          <listitem>
           <para>
            This is the section of an &aa; profile that refers to an
            include file, which procures 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. It is good practice
            to select includes when suggested.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Globbed version</term>
          <listitem>
           <para>
            This is accessed by selecting <guimenu>Glob</guimenu> as
            described in the next step. For information about globbing
            syntax, refer to <xref linkend="sec-apparmor-profiles-glob"/>.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Actual path</term>
          <listitem>
           <para>
            This is the literal path to which the program needs access so
            that it can run properly.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
        <para>
         After you select the path or include, process it as an entry into
         the &aa; profile by selecting <guimenu>Allow</guimenu> or
         <guimenu>Deny</guimenu>. If you are not satisfied with the
         directory path entry as it is displayed, you can also
         <guimenu>Glob</guimenu> it.
        </para>
        <para>
         The following options are available to process the learning mode
         entries and build the profile:
        </para>
        <variablelist>
         <varlistentry>
          <term>Select <keycap function="enter"/>
          </term>
          <listitem>
           <para>
            Allows access to the selected directory path.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Allow</term>
          <listitem>
           <para>
            Allows access to the specified directory path entries. &aa;
            suggests file permission access. For more information, refer to
            <xref linkend="sec-apparmor-profiles-perm"/>.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Deny</term>
          <listitem>
           <para>
            Prevents the program from accessing the specified directory path
            entries. &aa; then continues to the next event.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>New</term>
          <listitem>
           <para>
            Prompts you to enter your own rule for this event, allowing you
            to specify a regular expression. If the expression does not
            actually satisfy the event that prompted the question in the
            first place, &aa; asks for confirmation and lets you reenter
            the expression.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Glob</term>
          <listitem>
           <para>
            Select a specific path or create a general rule using wild cards
            that match a broader set of paths. To select any of the offered
            paths, enter the number that is printed in front of the path
            then decide how to proceed with the selected item.
           </para>
           <para>
            For more information about globbing syntax, refer to
            <xref linkend="sec-apparmor-profiles-glob"/>.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Glob w/ext</term>
          <listitem>
           <para>
            This modifies the original directory path while retaining the
            file name extension. For example,
            <filename>/etc/apache2/file.ext</filename> becomes
            <filename>/etc/apache2/*.ext</filename>, adding the wild card
            (asterisk) in place of the file name. This allows the program to
            access all files in the suggested directory that end with the
            <literal>.ext</literal> extension.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Abort</term>
          <listitem>
           <para>
            Aborts <command>aa-logprof</command>, losing all rule changes
            entered so far and leaving all profiles unmodified.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term>Finish</term>
          <listitem>
           <para>
            Closes <command>aa-logprof</command>, saving all rule changes
            entered so far and modifying all profiles.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </listitem>
      </itemizedlist>
     </step>
     <step>
      <para>
       To view and edit your profile using <command>vi</command>, enter
       <command>vi /etc/apparmor.d/</command>
       <replaceable>PROFILENAME</replaceable> in a terminal window. To
       enable syntax highlighting when editing an &aa; profile in vim,
       use the commands <command>:syntax on</command> then <command>:set
       syntax=apparmor</command>. For more information about vim and syntax
       highlighting, refer to
       <xref linkend="sec-apparmor-commandline-profiling-summary-vim"/>.
      </para>
     </step>
     <step>
      <para>
       Restart &aa; and reload the profile set including the newly
       created one using the <command>systemctl reload
       apparmor</command> command.
      </para>
     </step>
    </procedure>
    <para>
     Like the graphical front-end for building &aa; profiles, the
     &yast; Add Profile Wizard, <command>aa-genprof</command> also
     supports the use of the local profile repository under
     <filename>/usr/share/apparmor/extra-profiles</filename>.
    </para>
    <para>
     To use a profile from the local repository, proceed as follows:
    </para>
    <procedure>
     <step>
      <para>
       Start <command>aa-genprof</command> as described above.
      </para>
      <para>
       If <command>aa-genprof</command> finds an inactive local profile, the
       following lines appear on your terminal window:
      </para>
<screen>Profile: /usr/bin/opera

 [1 - Inactive local profile for /usr/bin/opera]

[(V)iew Profile] / (U)se Profile / (C)reate New Profile / Abo(r)t / (F)inish</screen>
     </step>
     <step>
      <para>
       To use this profile, press <keycap>U</keycap>
       (<guimenu>Use Profile</guimenu>) and follow the profile generation
       procedure outlined above.
      </para>
      <para>
       To examine the profile before activating it, press
       <keycap>V</keycap> (<guimenu>View Profile</guimenu>).
      </para>
      <para>
       To ignore the existing profile, press <keycap>C</keycap>
       (<guimenu>Create New Profile</guimenu>) and follow the profile
       generation procedure outlined above to create the profile from
       scratch.
      </para>
     </step>
     <step>
      <para>
       Leave <command>aa-genprof</command> by pressing <keycap>F</keycap>
       (<guimenu>Finish</guimenu>) when you are done and save your changes.
      </para>
     </step>
    </procedure>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-logprof">
    <title>aa-logprof&mdash;scanning the system log</title>
    <para>
     <command>aa-logprof</command> is an interactive tool used to review the
     complain and enforce mode events found in the log entries in
     <filename>/var/log/audit/audit.log</filename>, or directly in the
     &systemd; journal (see <xref linkend="cha-journalctl"/>), and
     generate new entries in &aa; security profiles.
    </para>
    <para>
     When you run <command>aa-logprof</command>, it begins to scan the log
     files produced in complain and enforce mode and, if there are new
     security events that are not covered by the existing profile set, it
     gives suggestions for modifying the profile.
     <command>aa-logprof</command> uses this information to observe program
     behavior.
    </para>
    <para>
     If a confined program forks and executes another program,
     <command>aa-logprof</command> sees this and asks the user which
     execution mode should be used when launching the child process. The
     execution modes <emphasis>ix</emphasis>, <emphasis>px</emphasis>,
     <emphasis>Px</emphasis>, <emphasis>ux</emphasis>,
     <emphasis>Ux</emphasis>, <emphasis>cx</emphasis>,
     <emphasis>Cx</emphasis>, and named profiles, are options for starting
     the child process. If a separate profile exists for the child process,
     the default selection is <emphasis>Px</emphasis>. If one does not
     exist, the profile defaults to <emphasis>ix</emphasis>. Child processes
     with separate profiles have <command>aa-autodep</command> run on them
     and are loaded into &aa;, if it is running.
    </para>
    <para>
     When <command>aa-logprof</command> exits, profiles are updated with the
     changes. If &aa; is active, the updated profiles are reloaded and,
     if any processes that generated security events are still running in
     the null-XXXX profiles (unique profiles temporarily created in complain
     mode), those processes are set to run under their proper profiles.
    </para>
    <para>
     To run <command>aa-logprof</command>, enter
     <command>aa-logprof</command> into a terminal window while logged in as
     &rootuser;. The following options can be used for
     <command>aa-logprof</command>:
    </para>
    <variablelist>
     <varlistentry>
      <term><command>aa-logprof -d</command><replaceable>/path/to/profile/directory/</replaceable>
      </term>
      <listitem>
       <para>
        Specifies the full path to the location of the profiles if the
        profiles are not located in the standard directory,
        <filename>/etc/apparmor.d/</filename>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><command>aa-logprof -f</command><replaceable>/path/to/logfile/</replaceable>
      </term>
      <listitem>
       <para>
        Specifies the full path to the location of the log file if the log
        file is not located in the default directory or
        <filename>/var/log/audit/audit.log</filename>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><command>aa-logprof -m "string marker in logfile"</command>
      </term>
      <listitem>
       <para>
        Marks the starting point for <command>aa-logprof</command> to look
        in the system log. <command>aa-logprof</command> ignores all events
        in the system log before the specified mark. If the mark contains
        spaces, it must be surrounded by quotes to work correctly. For
        example:
       </para>
<screen>&prompt.root;aa-logprof -m "17:04:21"</screen>
       <para>
        or
       </para>
<screen>&prompt.root;aa-logprof -m e2ff78636296f16d0b5301209a04430d</screen>
      </listitem>
     </varlistentry>
    </variablelist>
    <para>
     <command>aa-logprof</command> scans the log, asking you how to handle
     each logged event. Each question presents a numbered list of &aa;
     rules that can be added by pressing the number of the item on the list.
    </para>
    <para>
     By default, <command>aa-logprof</command> looks for profiles in
     <filename>/etc/apparmor.d/</filename>. Often running
     <command>aa-logprof</command> as &rootuser; is enough to update the
     profile. However, there might be times when you need to search archived
     log files, such as if the program exercise period exceeds the log
     rotation window (when the log file is archived and a new log file is
     started). If this is the case, you can enter <command>zcat -f `ls
     -1tr</command> <replaceable>/path/to/logfile*</replaceable>` |
     aa-logprof -f -.
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-logprof-ex1">
    <title>aa-logprof example 1</title>
    <para>
     The following is an example of how <command>aa-logprof</command>
     addresses httpd2-prefork accessing the file
     <filename>/etc/group</filename>. <literal>[]</literal> indicates the
     default option.
    </para>
    <para>
     In this example, the access to <command>/etc/group</command> is part of
     httpd2-prefork accessing name services. The appropriate response is
     <literal>1</literal>, which includes a predefined set of &aa; rules.
     Selecting <literal>1</literal> to <literal>#include</literal> the name
     service package resolves all of the future questions pertaining to DNS
     lookups and makes the profile less brittle in that any changes to
     DNS configuration and the associated name service profile package can
     be made once, rather than needing to revise many profiles.
    </para>
<screen>
Profile:  /usr/sbin/httpd2-prefork
Path:     /etc/group
New Mode: r

[1 - #include &lt;abstractions/nameservice&gt;]
 2 - /etc/group
[(A)llow] / (D)eny / (N)ew / (G)lob / Glob w/(E)xt / Abo(r)t / (F)inish
</screen>
    <para>
     Select one of the following responses:
    </para>
    <variablelist>
     <varlistentry>
      <term>Select <keycap function="enter"/>
      </term>
      <listitem>
       <para>
        Triggers the default action, which is, in this example, allowing
        access to the specified directory path entry.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Allow</term>
      <listitem>
       <para>
        Allows access to the specified directory path entries. &aa;
        suggests file permission access. For more information about this,
        refer to <xref linkend="sec-apparmor-profiles-perm"/>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Deny</term>
      <listitem>
       <para>
        Permanently prevents the program from accessing the specified
        directory path entries. &aa; then continues to the next event.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>New</term>
      <listitem>
       <para>
        Prompts you to enter your own rule for this event, allowing you to
        specify whatever form of regular expression you want. If the
        expression entered does not satisfy the event that prompted
        the question in the first place, &aa; asks for confirmation and
        lets you reenter the expression.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Glob</term>
      <listitem>
       <para>
        Select either a specific path or create a general rule using wild
        cards that matches on a broader set of paths. To select any of the
        offered paths, enter the number that is printed in front of the
        paths then decide how to proceed with the selected item.
       </para>
       <para>
        For more information about globbing syntax, refer to
        <xref linkend="sec-apparmor-profiles-glob"/>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Glob w/ext</term>
      <listitem>
       <para>
        This modifies the original directory path while retaining the file
        name extension. For example,
        <filename>/etc/apache2/file.ext</filename> becomes
        <filename>/etc/apache2/*.ext</filename>, adding the wild card
        (asterisk) in place of the file name. This allows the program to
        access all files in the suggested directory that end with the
        <literal>.ext</literal> extension.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Abort</term>
      <listitem>
       <para>
        Aborts <command>aa-logprof</command>, losing all rule changes
        entered so far and leaving all profiles unmodified.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Finish</term>
      <listitem>
       <para>
        Closes <command>aa-logprof</command>, saving all rule changes
        entered so far and modifying all profiles.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-logprof-ex2">
    <title>aa-logprof example 2</title>
    <para>
     For example, when profiling vsftpd, see this question:
    </para>
<screen>Profile:  /usr/sbin/vsftpd
Path:     /y2k.jpg
<!-- will probably be displayed as /path/to/chroot/y2k.jpg nowadays
See also the chroot_relative flag.
         -->
New Mode: r

[1 - /y2k.jpg]

(A)llow / [(D)eny] / (N)ew / (G)lob / Glob w/(E)xt / Abo(r)t / (F)inish
</screen>
    <para>
     Several items of interest appear in this question. First,
     vsftpd is asking for a path entry at the top of the tree, even though
     vsftpd on &productname;
<!-- without chroot_relative, you'll get /path/to/chroot/y2k.jpg, so you need to rewrite the whole section -->
     serves FTP files from <filename>/srv/ftp</filename> by default. This is
     because vsftpd uses chroot and, for the portion of the code inside the
     chroot jail, &aa; sees file accesses regarding the chroot
     environment rather than the global absolute path.
    </para>
    <para>
     The second item of interest is that you should grant FTP read
     access to all JPEG files in the directory, so you could use
     <guimenu>Glob w/Ext</guimenu> and use the suggested path of
     <literal>/*.jpg</literal>. Doing so collapses all previous rules
     granting access to individual <literal>.jpg</literal> files and
     forestalls any future questions pertaining to access to
     <filename>.jpg</filename> files.
    </para>
    <para>
     Finally, you should grant more general access to FTP files. If
     you select <guimenu>Glob</guimenu> in the last entry,
     <command>aa-logprof</command> replaces the suggested path of
     <filename>/y2k.jpg</filename> with <filename>/*</filename>.
     Alternatively, you should grant even more access to the entire
     directory tree, in which case you could use the <guimenu>New</guimenu>
     path option and enter <literal>/**.jpg</literal> (which would grant
     access to all <literal>.jpg</literal> files in the entire directory
     tree) or <filename>/**</filename> (which would grant access to all
     files in the directory tree).
    </para>
    <para>
     These items deal with read accesses. Write accesses are similar, except
     that it is good policy to be more conservative in your use of regular
     expressions for write accesses. Dealing with execute accesses is more
     complex. Find an example in
     <xref linkend="ex-apparmor-commandline-profiling-summary-genprof-learn"/>.
    </para>
    <para>
     In the following example, the <filename>/usr/bin/mail</filename> mail
     client is being profiled and <command>aa-logprof</command> has
     discovered that <command>/usr/bin/mail</command> executes
     <command>/usr/bin/less</command> as a helper application to
     <quote>page</quote> long mail messages. Consequently, it presents this
     prompt:
    </para>
<screen>
/usr/bin/nail -&gt; /usr/bin/less
(I)nherit / (P)rofile / (C)hild / (N)ame / (U)nconfined / (X)ix / (D)eny
</screen>
    <note>
     <para>
      The actual executable file for <filename>/usr/bin/mail</filename>
      turns out to be <filename>/usr/bin/nail</filename>, which is not a
      typographical error.
     </para>
    </note>
    <para>
     The program <filename>/usr/bin/less</filename> appears to be a
     simple one for scrolling through text that is more than one screen
     long and that is in fact what <filename>/usr/bin/mail</filename> is
     using it for. However, <command>less</command> is actually a large
     and powerful program that uses many other helper applications, such
     as <command>tar</command> and <command>rpm</command>.
    </para>
    <tip>
     <para>
      Run <command>less</command> on a tar file or an RPM file and it shows
      you the inventory of these containers.
     </para>
    </tip>
    <para>
     You do not want to run <command>rpm</command> automatically when
     reading mail messages (that leads directly to a Microsoft*
     Outlook&ndash;style virus attack, because RPM has the power to
     install and modify system programs), so, in this case, the best choice
     is to use <guimenu>Inherit</guimenu>. This results in the less program
     executed from this context running under the profile for
     <filename>/usr/bin/mail</filename>. This has two consequences:
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       You need to add all the basic file accesses for
       <filename>/usr/bin/less</filename> to the profile for
       <filename>/usr/bin/mail</filename>.
      </para>
     </listitem>
     <listitem>
      <para>
       You can avoid adding the helper applications, such as
       <command>tar</command> and <command>rpm</command>, to the
       <filename>/usr/bin/mail</filename> profile so that when
       <filename>/usr/bin/mail</filename> runs
       <filename>/usr/bin/less</filename> in this context, the less program
       is far less dangerous than it would be without &aa; protection.
       Another option is to use the Cx execute modes. For more information
       on execute modes, see <xref linkend="sec-apparmor-profiles-exec"/>.
      </para>
     </listitem>
    </itemizedlist>
    <para>
     In other circumstances, you might instead want to use the
     <guimenu>Profile</guimenu> option. This has the following effects on
     <command>aa-logprof</command>:
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       The rule written into the profile uses px/Px, which forces the
       transition to the child's own profile.
      </para>
     </listitem>
     <listitem>
      <para>
       <command>aa-logprof</command> constructs a profile for the child and
       starts building it, in the same way that it built the parent profile,
       by assigning events for the child process to the child's profile and
       asking the <command>aa-logprof</command> user questions. The profile
       will also be applied if you run the child as a stand-alone program.
      </para>
     </listitem>
    </itemizedlist>
    <para>
     If a confined program forks and executes another program,
     <command>aa-logprof</command> sees this and asks the user which
     execution mode should be used when launching the child process. The
     execution modes of inherit, profile, unconfined, child, named profile,
     or an option to deny the execution are presented.
    </para>
    <para>
     If a separate profile exists for the child process, the default
     selection is profile. If a profile does not exist, the default is
     inherit. The inherit option, or <literal>ix</literal>, is described in
     <xref linkend="sec-apparmor-profiles-perm"/>.
    </para>
    <para>
     The profile option indicates that the child program should run in its
     own profile. A secondary question asks whether to sanitize the
     environment that the child program inherits from the parent. If you
     choose to sanitize the environment, this places the execution modifier
     <literal>Px</literal> in your &aa; profile. If you select not to
     sanitize, <literal>px</literal> is placed in the profile and no
     environment sanitizing occurs. The default for the execution mode is
     <literal>Px</literal> if you select profile execution mode.
    </para>
    <para>
     The unconfined execution mode is not recommended and should only be
     used in cases where there is no other option to generate a profile for
     a program reliably. Selecting unconfined opens a warning dialog asking
     for confirmation of the choice. If you are sure and choose
     <guimenu>Yes</guimenu>, a second dialog ask whether to sanitize the
     environment. To use the execution mode <literal>Ux</literal> in your
     profile, select <guimenu>Yes</guimenu>. To use the execution mode
     <literal>ux</literal> in your profile instead, select
     <guimenu>No</guimenu>. The default value selected is
     <literal>Ux</literal> for unconfined execution mode.
    </para>
    <important>
     <title>Running unconfined</title>
     <para>
      Selecting <literal>ux or Ux</literal> is dangerous and provides
      no enforcement of policy (from a security perspective) of the
      resulting execution behavior of the child program.
     </para>
    </important>
   </sect3>
<!-- that all said:
         the aa-genprof and aa-logprof section have large parts of identical content.
         What about merging them?
         -->
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-unconfined">
    <title>aa-unconfined&mdash;identifying unprotected processes</title>
    <para>
     The <command>aa-unconfined</command> command examines open network
     ports on your system, compares that to the set of profiles loaded on
     your system, and reports network services that do not have &aa;
     profiles. It requires &rootuser; privileges and that it not be
     confined by an &aa; profile.
    </para>
    <para>
     <command>aa-unconfined</command> must be run as &rootuser; to
     retrieve the process executable link from the
     <filename>/proc</filename> file system. This program is susceptible to
     the following race conditions:
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       An unlinked executable is mishandled
      </para>
     </listitem>
     <listitem>
<!-- bnc#880080: netstat vs. ss/ip -->
      <para>
       A process that dies between <command>netstat(8)</command> and further
       checks is mishandled
      </para>
     </listitem>
    </itemizedlist>
    <note>
     <para>
      This program lists processes using TCP and UDP only. In short, this
      program is unsuitable for forensics use and is provided only as an aid
      to profiling all network-accessible processes in the lab.
     </para>
    </note>
   </sect3>
   <sect3 xml:id="commandline-profiling-summary-aa-notify">
    <title>aa-notify</title>
    <para>
     <command>aa-notify</command> is a handy utility that displays &aa;
     notifications in your desktop environment. This is convenient if
     you do not want to inspect the &aa; log file, but rather let the
     desktop inform you about events that violate the policy. To enable
     &aa; desktop notifications, run <command>aa-notify</command>:
    </para>
<screen>&prompt.sudo;aa-notify -p -u <replaceable>USERNAME</replaceable> --display <replaceable>DISPLAY_NUMBER</replaceable></screen>
    <para>
     where <replaceable>USERNAME</replaceable> is your user name under which
     you are logged in, and <replaceable>DISPLAY_NUMBER</replaceable> is the
     X Window display number you are currently using, such as
     <literal>:0</literal>. The process is run in the background, and shows
     a notification each time a deny event happens.
    </para>
    <tip>
     <para>
      The active X Window display number is saved in the
      <literal>$DISPLAY</literal> variable, so you can use
      <literal>--display $DISPLAY</literal> to avoid finding out the current
      display number.
     </para>
    </tip>
    <figure>
     <title><command>aa-notify Message in GNOME</command></title>
     <mediaobject>
      <imageobject role="fo">
       <imagedata fileref="aa-notify.png" width="75%"/>
      </imageobject>
      <imageobject role="html">
       <imagedata fileref="aa-notify.png" width="40%"/>
      </imageobject>
     </mediaobject>
    </figure>
    <para>
     With the <option>-s <replaceable>DAYS</replaceable></option> option,
     you can also configure <command>aa-notify</command> to display a
     summary of notifications for the specified number of past days. For
     more information on <command>aa-notify</command>, see its man page
     <command>man 8 aa-notify</command>.
    </para>
   </sect3>
   <sect3 xml:id="sec-apparmor-commandline-profiling-summary-vim">
    <title>apparmor.vim</title>
    <para>
     A syntax highlighting file for the vim text editor highlights various
     features of an &aa; profile with colors. Using vim and the &aa;
     syntax mode for vim, you can see the semantic implications of your
     profiles with color highlighting. Use vim to view and edit your profile
     by typing vim at a terminal window.
    </para>
    <para>
     To enable the syntax coloring when you edit an &aa; profile in vim,
     use the commands <literal>:syntax on</literal> then <literal>:set
     syntax=apparmor</literal>. To make sure vim recognizes the edited file
     type correctly as an &aa; profile, add
    </para>
<screen># vim:ft=apparmor</screen>
    <para>
     at the end of the profile.
    </para>
    <tip>
     <para>
      <command>vim</command> comes with &aa; highlighting automatically
      enabled for files in <filename>/etc/apparmor.d/</filename>.
     </para>
    </tip>
    <para>
     When you enable this feature, vim colors the lines of the profile for
     you:
    </para>
    <variablelist>
     <varlistentry>
      <term>Blue</term>
      <listitem>
       <para>
        Comments
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>White</term>
      <listitem>
       <para>
        Ordinary read access lines
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Brown</term>
      <listitem>
       <para>
        Capability statements and complain flags
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Yellow</term>
      <listitem>
       <para>
        Lines that grant write access
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Green</term>
      <listitem>
       <para>
        Lines that grant execute permission (either ix or px)
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Red</term>
      <listitem>
       <para>
        Lines that grant unconfined access (ux)
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Red background</term>
      <listitem>
       <para>
        Syntax errors that do not load properly into the &aa; modules
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
    <para>
     Use the <systemitem>apparmor.vim</systemitem> and
     <systemitem>vim</systemitem> man pages and the <option>:help
     syntax</option> from within the vim editor for further vim help about
     syntax highlighting. The &aa; syntax is stored in
     <filename>/usr/share/vim/current/syntax/apparmor.vim.</filename>
    </para>
   </sect3>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-commandline-filenames">
  <title>Important file names and directories</title>

  <para>
   The following list contains the most important files and directories used
   by the &aa; framework. If you intend to manage and troubleshoot your
   profiles manually, make sure that you know about these files and
   directories:
  </para>

  <variablelist>
   <varlistentry>
    <term><filename>/sys/kernel/security/apparmor/profiles</filename>
    </term>
    <listitem>
     <para>
      Virtualized file representing the currently loaded set of profiles.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/etc/apparmor/</filename>
    </term>
    <listitem>
     <para>
      Location of &aa; configuration files.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/usr/share/apparmor/extra-profiles</filename>
    </term>
    <listitem>
     <para>
      A local repository of profiles shipped with &aa;, but not enabled
      by default.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/etc/apparmor.d/</filename>
    </term>
    <listitem>
     <para>
      Location of profiles, named with the convention of replacing the
      <literal>/</literal> in paths with <literal>.</literal> (not for the
      root <literal>/</literal>) so profiles are easier to manage. For
      example, the profile for the program
      <filename>/usr/sbin/smbd</filename> is named
      <filename>usr.sbin.smbd</filename>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/etc/apparmor.d/abstractions/</filename>
    </term>
    <listitem>
     <para>
      Location of abstractions.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/etc/apparmor.d/program-chunks/</filename>
    </term>
    <listitem>
     <para>
      Location of program chunks.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/proc/*/attr/current</filename>
    </term>
    <listitem>
     <para>
      Check this file to review the confinement status of a process and the
      profile that is used to confine the process. The <command>ps</command>
      <option>auxZ</option> command retrieves this information
      automatically.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>
</chapter>