From 66f9f15e720845e9e6a65fe0a946f9e846e0c2ac Mon Sep 17 00:00:00 2001
From: Lars Erik Wik <lars.erik.wik@northern.tech>
Date: Fri, 7 Mar 2025 15:04:36 +0100
Subject: [PATCH] Added documentation on body fsattrs and the immutable
 constraint

Ticket: ENT-10961, CFE-1840
Signed-off-by: Lars Erik Wik <lars.erik.wik@northern.tech>
Co-authored-by: Nick Anderson <nick@cmdln.org>
---
 .../promise-types/files/_index.markdown       | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/content/reference/promise-types/files/_index.markdown b/content/reference/promise-types/files/_index.markdown
index d25289a3a..14aa66e1b 100644
--- a/content/reference/promise-types/files/_index.markdown
+++ b/content/reference/promise-types/files/_index.markdown
@@ -2749,6 +2749,59 @@ separator, since the backward slash has a special meaning in a regular
 expression. Literal paths may also use backslash (`\`) as a path
 separator.
 
+### fsattrs
+
+**Description:** Manage file system attributes
+
+**Type** `body fsattrs`
+
+**See also:** [Common body attributes][Promise types#Common body attributes]
+
+**Notes:**
+File system attributes are not supported on all file systems and platforms.
+Hence, CFEngine will do it on a best effort basis (without any guarantees).
+
+**History:**
+* Added in CFEngine 3.27.0
+
+#### immutable
+
+**Description:** Set / clear immutable file system attribute
+
+**Type:** [`boolean`][boolean]
+
+**Example:**
+
+```cf3
+body fsattrs set_immutable
+{
+  immutable => "true";
+}
+```
+
+**Notes:**
+Currently only regular files are supported when configuring the immutable bit.
+Furthermore, this will only work on Linux or BSD based systems with filesystems
+that support it. CFEngine will simply ignore the immutable constraint if it's
+not supported and instead log a verbose message (to avoid too much noise).
+
+- If the immutable constraint is set to `"true"` and the promised file:
+    - **is not** immutable; then the agent will perform all other actions promised
+      before setting the immutable bit.
+    - **is** immutable; then the agent will temporarily clear the immutable bit.
+      The agent will do its best to keep the period of the temporarily cleared bit
+      as short as possible. The immutable bit may be temporarily cleared multiple
+      times during a files promise.
+- If the immutable constraint set to `"false"` and the promised file **is**
+  immutable; then the immutable bit is cleared before performing any other
+  actions promised.
+- If the immutable constraint is unspecified and the promised file **is**
+  immutable; then the agent will fail to do any modifications on the file.
+
+**History:**
+
+* Added in CFEngine 3.27.0
+
 ### perms
 
 **Type:** `body perms`