[adding correct address of Alejandro]
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>
>
> ---
> 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.
> +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
> +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
>
