Hi,
On 5/21/22 08:40, Amir Goldstein wrote:
[adding correct address of Alejandro]
Thanks!
On Fri, May 20, 2022 at 9:09 PM Gabriel Krisman Bertazi
<krisman@xxxxxxxxxxxxx> wrote:
FAN_FS_ERROR is a new event for fanotify to report filesystem errors
that might lead to some corruption.
This documents how to use the feature and specific caveats.
Reviewed-by: Jan Kara <jack@xxxxxxx>
Reviewed-by: Amir Goldstein <amir73il@xxxxxxxxx>
Reviewed-by: Matthew Bobrowski <repnop@xxxxxxxxxx>
Signed-off-by: Gabriel Krisman Bertazi <krisman@xxxxxxxxxxxxx>
Please check a few minor formatting issues below.
Other than that, looks good to me.
However, it seems that I'm missing some patch, as I can't apply it to my
tree. Should I apply any other patch before this?
It doesn't apply on top of the kernel.org master branch either (but
don't use that one as reference, since it's quite old).
Thanks,
Alex
---
as discussed this is rebased on top of the PIDFD documentation: commit
207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature")
Which commit is that? From my tree?
Anyway, I see that Matthew has posted v4 since and Alejandro followed with v5.
Pushed v5 to fanotify_pidfd branch in my tree [1]
and this patch of yours (applies with no conflicts) to branch
fan-fs-error in my tree.
I also pushed branches fanotify_target_fid and fan_rename with a minor
update to include ENOTDIR error that was added in v5.18-rc7 and v5.17.9.
Matthew, the ENOTDIR change is minor so I kept your Reviewed-by.
Please ACK.
Thanks,
Amir.
[1] https://github.com/amir73il/man-pages
changes since v5:
(matthew)
- typo fix
changes since v4:
(Matthew)
- Grammar fixes
- Reword sections
(Jan)
- Explain fs error only apply to some errors
(Amir)
- Clarify what supported by ext4 means.
Changes since v3:
(Matthew)
- Rewording and fixes from github)
(amir)
- 5.15 -> 5.16
Changes since v2:
(matthew)
- Grammar
- List filesystems that support the feature
- file system -> filesystem
Changes since v1:
(Matthew)
- Grammar fixes
- Don't use the term "submitted" for events sent to the listener
- Clarify the kind of information that is file system specific
---
man2/fanotify_mark.2 | 30 +++++++++++++++++++++
man7/fanotify.7 | 64 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 94 insertions(+)
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 9a45cbb77893..3dc538b7f84b 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -203,6 +203,29 @@ Create an event when a marked file or directory itself is deleted.
An fanotify group that identifies filesystem objects by file handles
is required.
.TP
+.BR FAN_FS_ERROR " (since Linux 5.16)"
+.\" commit 9709bd548f11a092d124698118013f66e1740f9b
+Create an event when a filesystem error
+leading to inconsistent filesystem metadata is detected.
+An additional information record of type
+.B FAN_EVENT_INFO_TYPE_ERROR
+is returned for each event in the read buffer.
+An fanotify group that identifies filesystem objects by file handles
+is required.
+.IP
+Events of such type are dependent on support
+from the underlying filesystem.
+At the time of writing,
+only the
+.B ext4
+filesystem reports
+.B FAN_FS_ERROR
+events.
+.IP
+See
+.BR fanotify (7)
+for additional details.
+.TP
.BR FAN_MOVED_FROM " (since Linux 5.1)"
.\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
Create an event when a file or directory has been moved from a marked
@@ -391,6 +414,13 @@ and mask contains a flag for permission events
or
.BR FAN_ACCESS_PERM ).
.TP
+.B EINVAL
+The group was initialized without
+.B FAN_REPORT_FID
+but one or more event types specified in the
+.I mask
+require it.
+.TP
.B ENODEV
The filesystem object indicated by
.I pathname
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 57dd2b040380..3dc4113a551c 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -217,6 +217,25 @@ struct fanotify_event_info_pidfd {
.EE
.in
.PP
+In case of a
+.B FAN_FS_ERROR
+event,
+an additional information record describing the error that occurred
+is returned alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer.
+This structure is defined as follows:
+.PP
+.in +4n
+.EX
+struct fanotify_event_info_error {
+ struct fanotify_event_info_header hdr;
+ __s32 error;
+ __u32 error_count;
+};
+.EE
+.in
+.PP
All information records contain a nested structure of type
.IR fanotify_event_info_header .
This structure holds meta-information about the information record
@@ -358,6 +377,9 @@ A child file or directory was deleted in a watched parent.
.B FAN_DELETE_SELF
A watched file or directory was deleted.
.TP
+.B FAN_FS_ERROR
+A filesystem error was detected.
+.TP
.B FAN_MOVED_FROM
A file or directory has been moved from a watched parent directory.
.TP
@@ -630,6 +652,25 @@ Once the event listener has dealt with an event and the pidfd is no
longer required, the pidfd should be closed via
.BR close(2) .
.PP
+The fields of the
+.I fanotify_event_info_error
+structure are as follows:
+.TP
+.I hdr
+This is a structure of type
+.IR fanotify_event_info_header .
+The
+.I info_type
+field is set to
+.BR FAN_EVENT_INFO_TYPE_ERROR .
+.TP
+.I error
+Identifies the type of error that occurred.
+.TP
+.I error_count
+This is a counter of the number of errors suppressed
+since the last error was read.
+.PP
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
@@ -719,6 +760,29 @@ field.
In that case, the audit subsystem will log information about the access
decision to the audit logs.
.\"
+.SS Monitoring filesystems for errors
+A single FAN_FS_ERROR event is stored per filesystem at once.
.B FAN_FS_ERROR
(also a few more times below)
+Extra error messages are suppressed and accounted for
+in the
+.I error_count
+field of the existing FAN_FS_ERROR event record,
+but details about the errors are lost.
+.PP
+Errors reported by FAN_FS_ERROR are generic errno values
.I errno
+but not all kinds of error types are reported by all filesystems.
+.PP
+Errors not directly related to a file (i.e. super block corruption)
+are reported with an invalid
+.IR file_handle .
+For these errors, the
+.I file_handle
+will have the field
+.I handle_type
+set to
+.BR FILEID_INVALID ,
+and the handle buffer size set to
+.BR 0 .
+.\"
.SS Closing the fanotify file descriptor
When all file descriptors referring to the fanotify notification group are
closed, the fanotify group is released and its resources
--
2.36.1
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
