DEBOPS.APPARMOR(5)

NAME
debops.apparmor - Install and configure AppArmor

SYNOPSIS

debops run service/apparmor [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

AppArmor <https://apparmor.net/> is a Linux kernel Security Module (LSM) which provides mandatory access control <https://en.wikipedia.org/wiki/Mandatory_access_control>.

Programs are restricted on the basis of profiles, which are traditionally stored under /etc/apparmor.d/, using filenames which correspond to the path to the binary being protected by the profile (/usr/bin/foobar → /etc/apparmor.d/usr.bin.foobar).

Profiles can be configured in different modes: enforce, disabled, or complain (log, but don't enforce).

This role is primarily geared towards allowing other roles to perform customizations of existing profiles, and allowing administrators to selectively enable/disable profiles.

GETTING STARTED

  Using debops.apparmor from other roles

One common use case for debops.apparmor is to use it from other roles to perform customizations to the AppArmor profiles shipped with various packages and stored under the /etc/apparmor.d/ directory.

To do this, you can define the desired AppArmor modifications in your defaults/main.yml file. For example:

# Configuration for the ``debops.apparmor`` role, customizing the system
# profile for slapd to work in a DebOps environment.
slapd__apparmor__dependent_locals:
   - name: 'usr.sbin.slapd'
     options:
       - name: '/etc/pki/**'
         value: 'r'
         comment: 'Allow slapd access to DebOps PKI data'

And then in the playbook for this role, pass the slapd__apparmor__dependent_locals variable over to the debops.apparmor role:

---
- name: Manage OpenLDAP service
  ...
  hosts: [ 'debops_service_slapd']
  ...
  roles:
    - role: debops.apparmor
      tags: [ 'role::apparmor', 'skip::apparmor' ]
      apparmor__dependent_locals:
        - '{{ slapd__apparmor__dependent_locals }}'

There are three different variables which can be used to perform customizations of the local AppArmor configuration via role dependencies (apparmor__dependent_profiles, apparmor__dependent_locals and apparmor__dependent_tunables), see apparmor__profiles, apparmor__locals and apparmor__tunables for more details, including the syntax of each variable.

  Containers

WARNING: Note that AppArmor will not necessarily work properly inside containers and may cause issues with applications running in a containerized environment.

As an example, if you setup a systemd-nspawn(1) <https://manpages.debian.org/systemd-nspawn(1)> container/guest and AppArmor is enabled on the host system, the AppArmor profiles from the host will be enforced inside the container, even though they are not configured inside the container and tools such as aa-enabled will, if executed inside the container, report that AppArmor is not enabled.

Any changes to an AppArmor profile that interferes with the proper running of a given service would therefore have to be performed on the host, rather than the container/guest.

Your mileage might vary depending on the container technology used and its level (and maturity) of support for AppArmor.

  Example inventory

debops.apparmor is included by default in the common.yml DebOps playbook; you don't need to do anything to have it executed.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.apparmor role:

---
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Install and configure AppArmor
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_apparmor' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apparmor
      tags: [ 'role::apparmor', 'skip::apparmor' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after host is first configured to speed up playbook execution, when you are sure that most of the configuration has not been changed.

Available role tags:

role::apparmor
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::apparmor:pkg
    Tasks related to the installation of packages.

role::apparmor:grub
    Tasks related to the configuration of kernel parameters via GRUB.

role::apparmor:tunables
    Tasks related to the management of AppArmor tunables (i.e. files under /etc/apparmor.d/tunables/).

role::apparmor:locals
    Tasks related to the management of local modifications to AppArmor profiles (i.e. files under /etc/apparmor.d/local/).

role::apparmor:profiles
    Tasks related to the management of whether profiles should be in the enabled/disabled/complain state.

role::apparmor:service
    Tasks related to starting/stopping/enabling/disabling the AppArmor service.

  Other resources

List of other useful resources related to the debops.apparmor Ansible role:

•   Manual pages: apparmor(7) <https://manpages.debian.org/apparmor(7)>, apparmor.d(5) <https://manpages.debian.org/apparmor.d(5)> and the manpages for the various aa-* utilities (like aa-status(8) <https://manpages.debian.org/aa-status(8)>, aa-enabled(1) <https://manpages.debian.org/aa-enabled(1)>, aa-disable(8) <https://manpages.debian.org/aa-disable(8)>, aa-complain(8) <https://manpages.debian.org/aa-complain(8)> and aa-enforce(8) <https://manpages.debian.org/aa-enforce(8)>)

•   The website of the AppArmor Project <https://apparmor.net/>

•   The Ubuntu Wiki Page <https://wiki.ubuntu.com/AppArmor>

•   The Ubuntu Documentation <https://help.ubuntu.com/community/AppArmor>

•   The Debian Wiki Page <https://wiki.debian.org/AppArmor>, including the HowToUse <https://wiki.debian.org/AppArmor/HowToUse> subpage

AUTHOR
Robin Schneider, David Härdeman

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others