Hi Amir, On 6/17/22 15:00, Amir Goldstein wrote:
From: Gabriel Krisman Bertazi <krisman@xxxxxxxxxxxxx> 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> > --- Hi Alex, Posting v6 of Gabriel's patch with minor fixes per your request. Rebased on top of upstream.
Patch applied. Thanks! BTW, please check a comment below. Cheers, Alex
Thanks,
Amir.
man2/fanotify_mark.2 | 30 +++++++++++++++++++
man7/fanotify.7 | 71 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 101 insertions(+)
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 9a45cbb77..3dc538b7f 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 a0dc0dfba..f4d391603 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -228,6 +228,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;
+};
Since this is old, I'm applying it as is.But if you don't mind, I'd like to see types described in separate pages in the subsection 3type. So, for future pages, please consider that:).
See for example iovec(3type), or uint8_t(3type). <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=6c809df77b359bb3a9e06f32547e0aed155408be> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=cb3366169531510bcc7d445e15df68396291a05d> That helps keep information more organized, and deduplicate it. And makes it easy to check `man iovec` for a quick reference. This is following what started in man-pages-5.09 in system_data_types(7). <https://linux-man-pages.blogspot.com/2020/11/man-pages-509-is-released.html> See also: <https://stackoverflow.com/questions/55190317/where-is-ssize-t-defined-in-linux> <https://lore.kernel.org/linux-man/fb6463f6-49d7-e473-d5e1-1cdf8375e498@xxxxxxxxx/T/#u>
+.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 @@ -369,6 +388,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 @@ -643,6 +665,25 @@ 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) @@ -732,6 +773,36 @@ 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 +.B FAN_FS_ERROR +event is stored per filesystem at once. +Extra error messages are suppressed and accounted for in the +.I error_count +field of the existing +.B FAN_FS_ERROR +event record, +but details about the errors are lost. +.PP +Errors reported by +.B FAN_FS_ERROR +are generic +.I errno +values, +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
-- Alejandro Colomar <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
