mirror of
https://github.com/roddhjav/apparmor.d.git
synced 2024-11-15 07:54:17 +01:00
doc: add directives documentation.
This commit is contained in:
Alexandre Pujol
parent
88fcdd8c8e
commit
e979fe05b0
@ -18,38 +18,118 @@ For more access, simply use the [`dbus: talk`](#dbus-directive) directive.
|
|||||||
|
|
||||||
## Dbus Directive
|
## Dbus Directive
|
||||||
|
|
||||||
We use a special directive to generate (when running `make`) more advanced dbus access.
|
We use a special [directive](directives.md) to generate more advanced dbus access. The directive format is on purpose very similar to apparmor dbus rule.
|
||||||
|
|
||||||
**Directive format**
|
**Format**
|
||||||
```
|
|
||||||
#aa:dbus: ( own | talk ) bus=( system | session ) name=AARE [label=AARE] [interface=AARE] [path=AARE]
|
```sh
|
||||||
|
#aa:dbus <access> bus=<bus> name=<name> [label=AARE] [interface=AARE] [path=AARE]
|
||||||
```
|
```
|
||||||
|
|
||||||
The directive format is on purpose very similar to apparmor dbus rules. However, there are some restrictions:
|
**`<access>`**
|
||||||
|
|
||||||
- `bus` and `name` are mandatory and will break the build if ignored.
|
: Access type. Can be `own` or `talk`:
|
||||||
- For the *talk* sub directive, profile name under a `label` is also mandatory
|
|
||||||
- `interface` can optionally be given when it is different to the dbus path.
|
|
||||||
- `path` can optionally be given when it is different to the dbus name.
|
|
||||||
- It is still a comment: the rule must not end with a comma, multiline directive is not supported.
|
|
||||||
|
|
||||||
**Example:**
|
- `own` means the profile own this dbus interface. It is allowed to send and receive from anyone on this interface.
|
||||||
|
- `talk` means the profile can talk on a given interface to the profile owning it (that must be given under the `label` option).
|
||||||
|
|
||||||
|
**`<bus>`**
|
||||||
|
|
||||||
|
: Dbus bus, can be `system`, `session` or `accessibility`.
|
||||||
|
|
||||||
|
**`<name>`**
|
||||||
|
|
||||||
|
: Dbus interface name.
|
||||||
|
|
||||||
|
**`[label=AARE]`**
|
||||||
|
|
||||||
|
: Name of the profile
|
||||||
|
|
||||||
|
**`[interface=AARE]`**
|
||||||
|
|
||||||
|
: Can optionally be given when it is different to the dbus path.
|
||||||
|
|
||||||
|
**`[path=AARE]`**
|
||||||
|
|
||||||
|
: Can optionally be given when it is different to the dbus name.
|
||||||
|
|
||||||
|
|
||||||
|
Note: `<access>`, `<bus>` and `<name>` are mandatory and will break the build if ignored.
|
||||||
|
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
Allow owning a dbus interface:
|
Allow owning a dbus interface:
|
||||||
|
|
||||||
!!! note ""
|
!!! note ""
|
||||||
|
|
||||||
[apparmor.d/groups/network/NetworkManager](https://github.com/roddhjav/apparmor.d/blob/a3b15973640042af7da0ed540db690c711fbf6ec/apparmor.d/groups/network/NetworkManager#L46)
|
[apparmor.d/groups/network/NetworkManager](https://github.com/roddhjav/apparmor.d/blob/f81ceb91855f194dc53c10c17cbe1d7b50434a1e/apparmor.d/groups/network/NetworkManager#L45)
|
||||||
``` aa linenums="46"
|
``` sh linenums="45"
|
||||||
#aa:dbus: own bus=system name=org.freedesktop.NetworkManager
|
#aa:dbus own bus=system name=org.freedesktop.NetworkManager
|
||||||
```
|
```
|
||||||
|
|
||||||
Allow talking to a dbus interface on a given profile
|
Allow talking to a dbus interface on a given profile
|
||||||
|
|
||||||
!!! note ""
|
!!! note ""
|
||||||
|
|
||||||
[apparmor.d/groups/gnome/gdm](https://github.com/roddhjav/apparmor.d/blob/a3b15973640042af7da0ed540db690c711fbf6ec/apparmor.d/groups/gnome/gdm#L32)
|
[apparmor.d/groups/gnome/gdm](https://github.com/roddhjav/apparmor.d/blob/f81ceb91855f194dc53c10c17cbe1d7b50434a1e/apparmor.d/groups/gnome/gdm#L44)
|
||||||
``` aa linenums="32"
|
``` sh linenums="34"
|
||||||
#aa:dbus: talk bus=system name=org.freedesktop.login1 label=systemd-logind
|
#aa:dbus talk bus=system name=org.freedesktop.login1 label=systemd-logind
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Generate**
|
||||||
|
|
||||||
|
`#aa:dbus own bus=system name=org.freedesktop.NetworkManager`
|
||||||
|
|
||||||
|
:
|
||||||
|
```sh
|
||||||
|
dbus bind bus=system name=org.freedesktop.NetworkManager{,.*},
|
||||||
|
dbus receive bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.NetworkManager{,.*}
|
||||||
|
peer=(name=":1.@{int}"),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.DBus.Properties
|
||||||
|
peer=(name=":1.@{int}"),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.DBus.ObjectManager
|
||||||
|
peer=(name=":1.@{int}"),
|
||||||
|
dbus send bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.NetworkManager{,.*}
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.DBus}"),
|
||||||
|
dbus send bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.DBus.Properties
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.DBus}"),
|
||||||
|
dbus send bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.DBus.ObjectManager
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.DBus}"),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/NetworkManager{,/**}
|
||||||
|
interface=org.freedesktop.DBus.Introspectable
|
||||||
|
member=Introspect
|
||||||
|
peer=(name=":1.@{int}"),
|
||||||
|
```
|
||||||
|
|
||||||
|
`#aa:dbus talk bus=system name=org.freedesktop.login1 label=systemd-logind`
|
||||||
|
|
||||||
|
:
|
||||||
|
```sh
|
||||||
|
dbus send bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.login1{,.*}
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus send bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.DBus.Properties
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus send bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.DBus.ObjectManager
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.login1{,.*}
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.DBus.Properties
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus receive bus=system path=/org/freedesktop/login1{,/**}
|
||||||
|
interface=org.freedesktop.DBus.ObjectManager
|
||||||
|
peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
|
||||||
|
dbus send bus=system path=/org/freedesktop/Accounts{,/**}
|
||||||
|
interface=org.freedesktop.Accounts{,.*}
|
||||||
|
```
|
||||||
152
docs/development/directives.md
Normal file
152
docs/development/directives.md
Normal file
@ -0,0 +1,152 @@
|
|||||||
|
---
|
||||||
|
title: Directives
|
||||||
|
---
|
||||||
|
|
||||||
|
`apparmor.d` supports build directives, they are processed at build time of the project, when running `make`. They are valid apparmor comment, `apparmor_parser` can be used on a profile even if the directives have not been processed. They should not end with a comma. Multiline directive is not supported.
|
||||||
|
|
||||||
|
The directives follow the format:
|
||||||
|
```sh
|
||||||
|
#aa:<name> [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
**`<name>`**
|
||||||
|
|
||||||
|
: The name of the directive to apply
|
||||||
|
|
||||||
|
|
||||||
|
**`[options]`**
|
||||||
|
|
||||||
|
: A (possibly empty) list or map of arguments. Exact format depend on the directive.
|
||||||
|
|
||||||
|
## Dbus
|
||||||
|
|
||||||
|
See the [dbus page](dbus.md#dbus-directive).
|
||||||
|
|
||||||
|
|
||||||
|
## Only, Exclude
|
||||||
|
|
||||||
|
The `only` and `exclude` directive can be used to filter individual rule or rule paragraph depending on the target distribution of distribution family.
|
||||||
|
|
||||||
|
**Format**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#aa:only <filter>
|
||||||
|
#aa:exclude <filter>
|
||||||
|
```
|
||||||
|
|
||||||
|
**`<filter>`**
|
||||||
|
|
||||||
|
: The filter to apply. Can be:
|
||||||
|
|
||||||
|
- A supported target distribution: `arch`, `debian`, `ubuntu`, `opensuse`, `whonix`.
|
||||||
|
- A supported distribution family: `apt`, `pacman`, `zypper`.
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
!!! note ""
|
||||||
|
|
||||||
|
[apparmor.d/profiles-m-r/packagekitd](https://github.com/roddhjav/apparmor.d/blob/f81ceb91855f194dc53c10c17cbe1d7b50434a1e/apparmor.d/profiles-m-r/packagekitd#L99)
|
||||||
|
``` sh linenums="99"
|
||||||
|
#aa:only opensuse
|
||||||
|
@{run}/zypp.pid rwk,
|
||||||
|
owner @{run}/zypp-rpm.pid rwk,
|
||||||
|
owner @{run}/zypp/packages/ r,
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generate**
|
||||||
|
|
||||||
|
`#aa:only pacman`
|
||||||
|
|
||||||
|
:
|
||||||
|
Remove the line/paragraph when the project is not compiled on the Archlinux family.
|
||||||
|
|
||||||
|
|
||||||
|
## Exec
|
||||||
|
|
||||||
|
The `exec` directive is useful to allow executing transition to a profile without having to manage the possible long list of profile attachment (that varies depending on the distribution). The directive parse and resolve the attachment variable (`@{exec_path}`) of the target profile and include it in the current profile.
|
||||||
|
|
||||||
|
**Format**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#aa:exec [transition] profiles...
|
||||||
|
```
|
||||||
|
|
||||||
|
**`profiles...`**
|
||||||
|
|
||||||
|
: List of profile **file** that can be executed from the current profile.
|
||||||
|
|
||||||
|
**`[transition]`**
|
||||||
|
|
||||||
|
: Optional transition mode (default: `P`). Can be any of: `P`, `U`, `p`, `u`, `PU`, `pu`.
|
||||||
|
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
!!! note ""
|
||||||
|
|
||||||
|
[apparmor.d/groups/kde/ksmserver](https://github.com/roddhjav/apparmor.d/blob/f81ceb91855f194dc53c10c17cbe1d7b50434a1e/apparmor.d/groups/kde/ksmserver#L29)
|
||||||
|
``` sh linenums="29"
|
||||||
|
#aa:exec kscreenlocker_greet
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generate**
|
||||||
|
|
||||||
|
`#aa:exec baloo`
|
||||||
|
|
||||||
|
:
|
||||||
|
```sh
|
||||||
|
@{bin}/baloo_file Px,
|
||||||
|
@{lib}/@{multiarch}/{,libexec/}baloo_file Px,
|
||||||
|
@{lib}/{,kf6/}baloo_file Px,
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## Stack
|
||||||
|
|
||||||
|
[Stacked](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmorStacking) profiles can be hard to maintain. The *parents* profile need to manage its own rules as well as always include stacked profile rules. This directive automatically include the stacked profile rules into the parent profile.
|
||||||
|
|
||||||
|
**Format**
|
||||||
|
|
||||||
|
```sh
|
||||||
|
#aa:stack profiles...
|
||||||
|
```
|
||||||
|
|
||||||
|
**`profiles...`**
|
||||||
|
|
||||||
|
: List a profile **file** to stack at the end of the current profile.
|
||||||
|
|
||||||
|
|
||||||
|
**Example**
|
||||||
|
|
||||||
|
!!! note ""
|
||||||
|
|
||||||
|
[apparmor.d/_full/systemd](https://github.com/roddhjav/apparmor.d/blob/f81ceb91855f194dc53c10c17cbe1d7b50434a1e/apparmor.d/groups/_full/systemd#L150)
|
||||||
|
``` sh linenums="150"
|
||||||
|
#aa:stack systemd-networkd systemd-oomd systemd-resolved systemd-timesyncd
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generate**
|
||||||
|
|
||||||
|
`#aa:stack systemd-oomd`
|
||||||
|
|
||||||
|
:
|
||||||
|
```sh
|
||||||
|
# Stacked profile: systemd-oomd
|
||||||
|
include <abstractions/bus-system>
|
||||||
|
include <abstractions/systemd-common>
|
||||||
|
capability dac_override,
|
||||||
|
capability kill,
|
||||||
|
unix (bind) type=stream addr=@@{hex}/bus/systemd-oomd/bus-api-oom,
|
||||||
|
#aa:dbus own bus=system name=org.freedesktop.oom1
|
||||||
|
/etc/systemd/oomd.conf r,
|
||||||
|
/etc/systemd/oomd.conf.d/{,**} r,
|
||||||
|
@{run}/systemd/io.system.ManagedOOM rw,
|
||||||
|
@{run}/systemd/io.systemd.ManagedOOM rw,
|
||||||
|
@{run}/systemd/notify rw,
|
||||||
|
owner @{run}/systemd/journal/socket w,
|
||||||
|
@{sys}/fs/cgroup/cgroup.controllers r,
|
||||||
|
@{sys}/fs/cgroup/memory.pressure r,
|
||||||
|
@{sys}/fs/cgroup/user.slice/user-@{uid}.slice/user@@{uid}.service/memory.* r,
|
||||||
|
@{PROC}/pressure/{cpu,io,memory} r,
|
||||||
|
include if exists <local/systemd-oomd>
|
||||||
|
```
|
||||||
@ -91,6 +91,7 @@ markdown_extensions:
|
|||||||
- md_in_html
|
- md_in_html
|
||||||
- toc:
|
- toc:
|
||||||
permalink: true
|
permalink: true
|
||||||
|
toc_depth: 3
|
||||||
- pymdownx.betterem:
|
- pymdownx.betterem:
|
||||||
smart_enable: all
|
smart_enable: all
|
||||||
- pymdownx.caret
|
- pymdownx.caret
|
||||||
@ -143,6 +144,8 @@ nav:
|
|||||||
- development/install.md
|
- development/install.md
|
||||||
- development/guidelines.md
|
- development/guidelines.md
|
||||||
- development/structure.md
|
- development/structure.md
|
||||||
|
- Profiles:
|
||||||
|
- development/directives.md
|
||||||
- development/dbus.md
|
- development/dbus.md
|
||||||
- Tests:
|
- Tests:
|
||||||
- development/tests.md
|
- development/tests.md
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user