From cce5bd6e95ae9a9f01caceea0d5d75b612dd3fbc Mon Sep 17 00:00:00 2001
From: John Johansen <john.johansen@canonical.com>
Date: Mon, 10 Feb 2025 12:00:06 -0800
Subject: [PATCH] man apparmor.d: document how variable expansion and path
 sanitization works

The documentation was missing information about path sanitization, and
why you shouldn't do a leading @{VAR} on path rules. While the example
doing this was fixed, actual information about why you shouldn't do
this was missing.

Document how apparmor will collapse consecutive / characters into a
single character for paths, except when this occurs at the start of
the path.

Signed-off-by: John Johansen <john.johansen@canonical.com>
---
 parser/apparmor.d.pod | 55 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod
index f9045196a..a8b27b63a 100644
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -1796,6 +1796,61 @@ F</etc/apparmor.d/tunables/xdg-user-dirs.d> for B<@{XDG_*}>.
 The special B<@{profile_name}> variable is set to the profile name and may be
 used in all policy.
 
+=head3 Notes on variable expansion and the / character
+
+It is important to note that how AppArmor performs variable expansion
+depends on the context where a variable is used. When a variable is
+expanded it can result in a string with multiple path characters
+next to each other, in a way that is not evident when looking at
+policy.
+
+Eg.
+
+=over 4
+
+Given the following variable definition and rule
+
+@{HOME}=/home/*/
+file rw @{HOME}/*,
+
+The variable expansion results in a rule of
+
+file rw /home/*//*.
+
+=back
+
+When this occurs in a context where a path is expected, AppArmor will
+canonicalize the path by collapsing consecutive / characters into
+a single character. For the above example, this would be
+
+  file rw /home/*/*,
+
+There is one exception to this rule, when the consecutive / characters
+are at the beginning of a path, this indicates a posix namespace
+and the characters will not be collapsed.
+
+Eg.
+
+=over 4
+
+@{HOME}=/home/*/
+file rw /@{HOME}/*,
+
+will result in an expansion of
+
+file rw //home/*//*,
+
+which is collapsed to
+
+file rw //home/*/*,
+
+Note: that the leading // in the above example is not collapsed to a
+single /. However the second // (that was also seen in the first
+example) is collapsed.
+
+=back
+
+
 =head2 Alias rules
 
 AppArmor also provides alias rules for remapping paths for site-specific