From 70202c047f8f095eb356cfc9ea87d77f0d87bf89 Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:23 +0200 Subject: [PATCH 1/6] Documented the file_created event type file_created fires when a file appears at the watched path. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index 4c1ae7397..a656433e2 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -146,3 +146,22 @@ body when deleted(file) **Type:** `string` **Allowed input range:** (arbitrary string) + +##### File created + +**Description:** Creates an event when a file is created at the given path. + +The event fires when the path was missing at one check and exists at the next one. +It fires once per creation: the file has to be deleted again before another creation is detected. +Any type of file counts, for example a directory or a symlink, even one whose target does not exist. + +```cf3 +body when created(file) +{ + file_created => "$(file)"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) From 390eda1e2c7b41179b1c3e168e6836b1e6ad98e0 Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:24 +0200 Subject: [PATCH 2/6] Documented the file_modified event type file_modified fires when the modification time of the watched file changes. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index a656433e2..2a5110bc8 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -165,3 +165,26 @@ body when created(file) **Type:** `string` **Allowed input range:** (arbitrary string) + +##### File modified + +**Description:** Creates an event when the modification time of the file at the given path changes. + +The event fires when the file exists at two consecutive checks with different modification times. +Writing to the file changes its modification time, but so does touching it without changing its content. +For a directory, creating, renaming or deleting a file in it changes its modification time. +Changing the permissions or the owner of the file doesn't change its modification time. +Symlinks are not followed: the modification time is the one of the symlink itself, not of its target. + +```cf3 +body when modified(file) +{ + file_modified => "$(file)"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) + +**See also:** [`file_content_modified`](#file-content-modified) From b3d30314cc451dbb325eb6a79bbe38ee401dbfb5 Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:24 +0200 Subject: [PATCH 3/6] Documented the file_content_modified event type file_content_modified fires when the SHA-256 hash of the content of the watched regular file changes. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index 2a5110bc8..fa4a591e1 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -188,3 +188,23 @@ body when modified(file) **Allowed input range:** (arbitrary string) **See also:** [`file_content_modified`](#file-content-modified) + +##### File content modified + +**Description:** Creates an event when the content of the regular file at the given path changes. + +The event fires when the path is a regular file at two consecutive checks and the SHA-256 hash of its content differs. +Unlike [`file_modified`](#file-modified), touching the file or replacing it with a file of the same content is not a modification. +The file is read on every check, so it is more expensive than `file_modified` for large files. +Directories and symlinks have no content to hash, so they never fire this event. + +```cf3 +body when content_modified(file) +{ + file_content_modified => "$(file)"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) From adc2072e2961ab01f23ddc40e180e77be7f5cea6 Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:24 +0200 Subject: [PATCH 4/6] Documented the file_permissions_changed event type file_permissions_changed fires when the permission bits (07777) of the watched file change. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index fa4a591e1..d1ddacdd2 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -208,3 +208,21 @@ body when content_modified(file) **Type:** `string` **Allowed input range:** (arbitrary string) + +##### File permissions changed + +**Description:** Creates an event when the permissions of the file at the given path change. + +The event fires when the file exists at two consecutive checks with different permission bits, including the setuid, setgid and sticky bits. +Symlinks are not followed: changing the permissions of the target of a symlink does not fire the event for the symlink. + +```cf3 +body when permissions_changed(file) +{ + file_permissions_changed => "$(file)"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) From a39760fcbf79dde425b25ba328b1b4dc869174bb Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:25 +0200 Subject: [PATCH 5/6] Documented the file_owner_changed event type file_owner_changed fires when the owning user or group of the watched file changes. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index d1ddacdd2..48c641d61 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -226,3 +226,21 @@ body when permissions_changed(file) **Type:** `string` **Allowed input range:** (arbitrary string) + +##### File owner changed + +**Description:** Creates an event when the owning user or group of the file at the given path changes. + +The event fires when the file exists at two consecutive checks with a different owning user or group. +Symlinks are not followed: changing the owner of the target of a symlink does not fire the event for the symlink. + +```cf3 +body when owner_changed(file) +{ + file_owner_changed => "$(file)"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) From b8be8b4ec43ff55522b173dd0038e9beb2387282 Mon Sep 17 00:00:00 2001 From: Victor Moene Date: Fri, 23 Oct 2026 12:14:25 +0200 Subject: [PATCH 6/6] Documented the file_size_exceeds event type file_size_exceeds fires when the size of the watched file grows above size_threshold bytes. Also documented the size_threshold attribute it requires. Ticket: ENT-14692 Signed-off-by: Victor Moene --- .../reference/promise-types/events.markdown | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/content/reference/promise-types/events.markdown b/content/reference/promise-types/events.markdown index 48c641d61..229a68a0b 100644 --- a/content/reference/promise-types/events.markdown +++ b/content/reference/promise-types/events.markdown @@ -244,3 +244,33 @@ body when owner_changed(file) **Type:** `string` **Allowed input range:** (arbitrary string) + +##### File size exceeds + +**Description:** Creates an event when the size of the file at the given path grows above [`size_threshold`](#size_threshold) bytes. + +The event fires when the file is above the threshold at one check, and was below it or didn't exist at the previous one. +It fires once per crossing of the threshold: the file has to be below it at a check, for example after being truncated, before it can fire again. +A file created with a size above the threshold fires the event. + +```cf3 +body when size_exceeds(file) +{ + file_size_exceeds => "$(file)"; + size_threshold => "1048576"; +} +``` + +**Type:** `string` + +**Allowed input range:** (arbitrary string) + +##### size_threshold + +**Description:** The size, in bytes, above which [`file_size_exceeds`](#file-size-exceeds) fires. + +Required with `file_size_exceeds`, and can't be used with other event types. + +**Type:** `int` + +**Allowed input range:** `0,99999999999`