Default variable details
Some of the debops.apparmor
default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.
apparmor__profiles
The apparmor__*_profiles
variables define which profiles should be
enabled or disabled, following the principles of
universal configuration.
Examples
Define the state of a couple of profiles:
apparmor__profiles:
- name: 'usr.sbin.nmbd'
state: 'complain'
- name: 'usr.sbin.smbd'
state: 'enforce'
- name: 'usr.sbin.traceroute'
state: 'disable'
- name: 'usr.local.sbin.legacy'
state: 'ignore'
Syntax
The AppArmor profile configuration options uses YAML dictionaries with the following parameters:
name
Required. Name of the profile under the
/etc/apparmor.d/
directory. Configuration entries with the samename
parameter are merged in order of appearance; this can be used to change configuration options conditionally.state
Required. The desired state of the given profile. Valid states are:
enforce
Results in the enforcement of the policy defined in the profile; policy violation attempts will be blocked and logged.
complain
The policy will not be enforced (with some caveats, as noted in the aa-complain(8) man page, deny rules are still enforced), but policy violations will be logged.
disable
The policy will not be loaded; policy violations will be neither blocked nor logged.
ignore
The state of the given policy will not be changed. This is useful to override more generic configuration.
apparmor__locals
The apparmor__*_locals
variables define modifications to system
profiles. The variables define file fragments which are placed under
/etc/apparmor.d/local/
, and can be used to fine-tune existing profiles
to meet site-specific requirements.
In order to determine the correct name for an override, have a look at the profile which needs to be further customized:
# cat /etc/apparmor.d/usr.sbin.nscd
...
# Site-specific additions and overrides. See local/README for details.
#include <local/usr.sbin.nscd>
}
Here, the relevant modification for /etc/apparmor.d/usr.sbin.nscd
would be /etc/apparmor.d/local/usr.sbin.nscd
. The debops.apparmor
role will automatically prepend the /etc/apparmor.d/local/
part, so
the modification should simply be named usr.sbin.nscd
.
This is the case for most profiles.
As noted in /etc/apparmor.d/local/README
:
Note
Keep in mind that 'deny' rules are evaluated after allow rules, so you won't be able to allow access to files that are explicitly denied by the shipped profile using this mechanism.
Examples
Define modifications for two profiles (showing three different possible syntaxes for a given configuration option):
apparmor__locals:
- name: 'usr.sbin.dnsmasq'
options:
- name: 'dnsmasq-allow-resolvconf'
comment: 'Allow dnsmasq to read upstream DNS servers'
option: '/etc/resolvconf/upstream.conf'
value: 'r'
- name: '/etc/hosts.dnsmasq'
value: 'r'
- name: 'usr.bin.pidgin'
options:
- name: 'pidgin-allow-home-plugins'
comment: 'Allow per-user Pidgin plugins'
raw: '@{HOME}/.purple/plugins/** rm,'
Syntax
The AppArmor profile modification options uses YAML dictionaries with the following parameters:
name
Required. Name of the local modification file under the
/etc/apparmor.d/local/
directory. Note that subdirectories are also supported, so ifname
is set tofoo/bar
, the result will be written to/etc/apparmor.d/local/foo/bar
. Configuration entries with the samename
parameter are merged in order of appearance; this can be used to change configuration options conditionally.state
Optional. If not specified or
present
, the configuration file will be created, or a given configuration option (seeoptions
below) will be present in the configuration file. Ifabsent
, a given file/option will be removed. Ifinit
orignore
, the configuration file/option won't be created/included - this can be used e.g. to prepare configuration that will be activated conditionally someplace else. Ifcomment
, a given configuration option will be present, but commented out.options
Optional. A list of YAML dictionaries with options which should be written to the modification file, valid parameters include
name
andstate
, as explained above, plus the following parameters:option
Optional. A string which, if defined, will be used instead of the
name
parameter when generating the configuration file.value
Optional. A string which will be used together with
name
oroption
to generate a line in the generated configuration file.operator
Optional. A string defining the operator used to combine the
name
oroption
andvalue
in the generated configuration file. The default is a space (unless the template detects that a different operator should be used, based on thename
oroption
).suffix
Optional. A string which should be added at the end of the configuration option in the generated configuration file. The default is a comma.
raw
Optional. String or YAML text block which will be included in the generated configuration file "as is". If the
raw
parameter is defined, it takes precedence overname
,option
,value
,operator
andsuffix
.comment
Optional. String or YAML text block with comments about a given configuration option.
separator
Optional, boolean. If defined and
True
, the role will add an empty line before a given configuration option, to allow for better readability.weight
Optional. Positive or negative number which defines the additional "weight" of an option. Smaller or negative weight will move the option higher in the configuration file, higher weight will move the configuration option lower in the configuration file.
options
Optional. Same format as
options
above. An option which contains suboptions will be rendered as a configuration block with theoption
orname
value of the parent option as the name of the configuration block.
The TL;DR; version is that options will generally be rendered in the generated configuration file as:
(option.option | option.name) + option.operator + option.value + option.suffix
So a configuration like this:
- name: 'usr.sbin.named'
options:
- name: '/etc/pki/**'
operator: ' '
value: 'r'
suffix: ','
Is equivalent to a configuration like this:
- name: 'usr.sbin.named'
options:
- name: 'allow-pki-access'
option: '/etc/pki/**'
value: 'r'
And both will result in the following line being included in the generated configuration file:
/etc/pki/** r,
apparmor__tunables
The apparmor__*_tunables
variables are similar to the
apparmor__locals variables, but instead define the content of
file fragments in the /etc/apparmor.d/tunables/
directory.
The tunables which are supported depends on the profiles which are already installed, and covering them all is outside the scope of this documentation.
See the existing files under /etc/apparmor.d/tunables/
to get a
better feeling for what is possible and not. Also, see the tunables section
from the Ubuntu wiki for more details.
Examples
Define an additional path under which user home directories are stored:
apparmor__tunables:
- name: 'home.d/site.local'
options:
- name: 'add-home-dirs'
comment: 'Define additional home directory locations'
option: '@{HOMEDIRS}'
operator: '+='
value: '/srv/nfs/home/ /mnt/home/'
Syntax
The AppArmor tunables options use YAML dictionaries with the same syntax as apparmor__locals.
The only difference is that the default value for operator
is =
and
the default value for suffix
is no suffix.