From 4fe03b7417b39ab6f310f5f398808a42acd05f16 Mon Sep 17 00:00:00 2001
From: Alexandre Pujol <alexandre@pujol.io>
Date: Sat, 18 Feb 2023 18:24:14 +0000
Subject: [PATCH] docs: add browser related details, add some links in
 guidelines.

---
 docs/development/guidelines.md | 24 ++++++++++++------------
 docs/development/structure.md  | 20 ++++++++++++++++++++
 2 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/docs/development/guidelines.md b/docs/development/guidelines.md
index e672b245..3a87bf7f 100644
--- a/docs/development/guidelines.md
+++ b/docs/development/guidelines.md
@@ -33,20 +33,20 @@ follow the guidelines presented here.
 
 The rules in the profile should be sorted in the rule ***block*** as follows:
 
-1. `include`
-1. `set rlimit`
-1. `capability`
-1. `network`
-1. `mount`
-1. `remount`
-1. `umount`
-1. `pivot_root`
-1. `change_profile`
-1. `signal`
+1. [`include`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#include-statements)
+1. [`set rlimit`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#rlimit-rules)
+1. [`capability`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#capability-rules)
+1. [`network`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#network-rules)
+1. [`mount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#mount-rules-apparmor-28-and-later)
+1. [`remount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#remount)
+1. [`umount`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#umount)
+1. [`pivot_root`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#pivot_root)
+1. [`change_profile`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#change_profile)
+1. [`signal`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#signals)
 1. `ptrace`
 1. `unix`
-1. `dbus`
-1. `file`
+1. [`dbus`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#dbus-rules)
+1. [`file`](https://gitlab.com/apparmor/apparmor/-/wikis/AppArmor_Core_Policy_Reference#file-access-rules)
 1. local include
 
 This rule order is taken from AppArmor with minor changes as we tend to:
diff --git a/docs/development/structure.md b/docs/development/structure.md
index 90650828..47986346 100644
--- a/docs/development/structure.md
+++ b/docs/development/structure.md
@@ -138,6 +138,26 @@ Here is an overview of the current children profile:
    of the time you will need more privilege than what this profile is giving you.
 
 
+## Browsers
+
+Chromium based browsers share a similar structure. Therefore, they share the same
+abstraction: [`abstractions/chromium`][chromium] that includes most of the profile content.
+
+This abstraction requires the following variables definied in the profile header:
+```sh
+@{chromium_name} = chromium
+@{chromium_domain} = org.chromium.Chromium
+@{chromium_lib_dirs} = /{usr/,}lib/chromium
+@{chromium_config_dirs} = @{user_config_dirs}/chromium
+@{chromium_cache_dirs} = @{user_cache_dirs}/chromium
+```
+
+If your application requires chromium to run (like electron) use
+[`abstractions/chromium-common`][chromium-common] instead.
+
+[chromium]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium
+[chromium-common]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/abstractions/chromium-common
+
 ## Udev rules
 
 See the **[kernel docs][kernel]** to check the major block and char numbers used in `/run/udev/data/`.