From 7915161dbf136e36848fd12c8757ef8471297625 Mon Sep 17 00:00:00 2001
From: Victor Moene <victor.moene@northern.tech>
Date: Mon, 22 Sep 2025 14:10:29 +0200
Subject: [PATCH] Added documentation for policy function findlocalgroups

Ticket: CFE-4550
Signed-off-by: Victor Moene <victor.moene@northern.tech>
---
 .../functions/findlocalgroups.markdown        | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 content/reference/functions/findlocalgroups.markdown

diff --git a/content/reference/functions/findlocalgroups.markdown b/content/reference/functions/findlocalgroups.markdown
new file mode 100644
index 000000000..49950df6c
--- /dev/null
+++ b/content/reference/functions/findlocalgroups.markdown
@@ -0,0 +1,51 @@
+---
+layout: default
+title: findlocalgroups
+---
+
+{{< CFEngine_function_prototype(filter) >}}
+
+**Description:** Returns a data container of all local groups with their attributes that are matching a filter. If no filter is specified, it will return all the local groups.
+
+{{< CFEngine_function_attributes(filter) >}}
+
+The `filter` argument can be used to look up groups with specific attributes that match values. The filter is a `"data"` container array or `"slist"` comprised of pairs of attribute and value/regex pattern `{ "attribute1=value1", "attribute2=value2", ... }`.
+
+The possible attributes are:
+
+- `name`: name
+- `gid`: group id
+- `member` members: a list of users separated by commas
+
+**Example:**
+
+```cfengine3
+bundle agent main
+{
+  vars:
+    "filter" slist => { "name=root" };
+    "groups" data => findlocalgroups("@(filter)");
+
+  reports:
+    "$(with)" with => storejson("@(groups)");
+}
+```
+
+Output:
+
+```
+R: {
+  "root": {
+    "gid": 0,
+    "members": []
+  }
+}
+```
+
+**Notes:**
+
+- This function is currently only available on Unix-like systems.
+
+**History:**
+
+- Function added in 3.27.0.