fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR

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 <[email protected]>

Reviewed-by Amir Goldstein <[email protected]>

Reviewed-by Matthew Bobrowski <[email protected]>

Signed-off-by Gabriel Krisman Bertazi <[email protected]>

---
as discussed this is rebased on top of the PIDFD documentation: commit 207080c7f7f5 ("fanotify: Document FAN_REPORT_PIDFD Feature")

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(+)

man2/fanotify_mark.2 +30 -0

index 9a45cbb77893..3dc538b7f84b 100644
@@ -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

man7/fanotify.7 +64 -1

index 57dd2b040380..3dc4113a551c 100644
@@ -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

[adding correct address of Alejandro]

Quoted 1 line · Gabriel Krisman Bertazi

Quoted 8 lines

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 <[email protected]>

Reviewed-by Amir Goldstein <[email protected]>

Reviewed-by Matthew Bobrowski <[email protected]>

Signed-off-by Gabriel Krisman Bertazi <[email protected]>

Quoted 4 lines

---
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

Quoted 147 lines

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(+)

man2/fanotify_mark.2 +30 -0

index 9a45cbb77893..3dc538b7f84b 100644
@@ -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

man7/fanotify.7 +41 -0

index 57dd2b040380..3dc4113a551c 100644
@@ -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

man7/fanotify.7 field. · line 764

Quoted 8 lines

man7/fanotify.7 +2 -0

  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.

man7/fanotify.7 field. · line 771

Quoted 7 lines

man7/fanotify.7 +7 -0

+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

Quoted 20 lines

man7/fanotify.7 +14 -1

+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

Hi,

Quoted 1 line · Amir Goldstein

[adding correct address of Alejandro]

Thanks!

Quoted 4 lines

Quoted 1 line · Gabriel Krisman Bertazi

Quoted 8 lines

Quoted 8 lines

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 <[email protected]>

Reviewed-by Amir Goldstein <[email protected]>

Reviewed-by Matthew Bobrowski <[email protected]>

Signed-off-by Gabriel Krisman Bertazi <[email protected]>

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).

It is applied on top of:

https://lore.kernel.org/linux-man/[email protected]/T/#u

We have a rather long backlog of man page updates pending merge from Matthew, Gabriel and myself.
We need to merge them by order.
The entire stack is available in [BRANCHES] on my github tree [1].

Let me summarize it for you again:

FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

FAN_FS_ERROR v5.16 [fan-fs-error]

FAN_REPORT_TARGET_FID v5.17 [fanotify_target_fid]

FAN_RENAME v5.17 [fan_rename]

And I have more changes for upcoming v5.19... >
Let me know if anything is not clear.

BTW, is there any prospect of updating kernel.org man pages anytime soon?

Thanks,
Amir.

[1] https://github.com/amir73il/man-pages

Hi Amir,

Quoted 3 lines · Amir Goldstein

It is applied on top of:

https://lore.kernel.org/linux-man/[email protected]/T/#u

Okay, I see that other one is pending some rewording, so I'll hold this one.

Quoted 7 lines

We have a rather long backlog of man page updates pending merge from Matthew, Gabriel and myself.
We need to merge them by order.
The entire stack is available in [BRANCHES] on my github tree [1].

Let me summarize it for you again:

Thanks. I'll write here what I know about the, just to be sure I didn't miss anything. If you need anything from me, please tell me.

Quoted 2 lines

FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

Pending a rewording of a paragraph.

Quoted 21 lines · Alejandro Colomar

Hi Amir,

Quoted 3 lines · Amir Goldstein

It is applied on top of:

https://lore.kernel.org/linux-man/[email protected]/T/#u

Okay, I see that other one is pending some rewording, so I'll hold this one.

Quoted 7 lines

We have a rather long backlog of man page updates pending merge from Matthew, Gabriel and myself.
We need to merge them by order.
The entire stack is available in [BRANCHES] on my github tree [1].

Let me summarize it for you again:

Thanks. I'll write here what I know about the, just to be sure I didn't miss anything. If you need anything from me, please tell me.

Quoted 1 line

Quoted 3 lines

Quoted 1 line

FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

Pending a rewording of a paragraph.

Right, I'll get around to this at some point today.

Quoted 7 lines

We have a rather long backlog of man page updates pending merge from Matthew, Gabriel and myself.
We need to merge them by order.
The entire stack is available in [BRANCHES] on my github tree [1].

Quoted 1 line

Let me summarize it for you again:

Thanks. I'll write here what I know about the, just to be sure I didn't miss anything. If you need anything from me, please tell me.

Quoted 2 lines

FAN_REPORT_PIDFD v5.15 [fanotify_pidfd]

Pending a rewording of a paragraph.

Quoted 1 line

FAN_FS_ERROR v5.16 [fan-fs-error]

This one. Looks good to me.

Quoted 1 line

FAN_REPORT_TARGET_FID v5.17 [fanotify_target_fid]

I don't see this one in my mbox or linux-man@.
I assume it's not yet ready?

Quoted 1 line

FAN_RENAME v5.17 [fan_rename]

I don't see this either. I assume it's not ready either.

Quoted 2 lines

And I have more changes for upcoming v5.19... >

I see you finally managed to flow this into kernel.org repo. Yay! :)

Quoted 4 lines

Quoted 1 line

FAN_FS_ERROR v5.16 [fan-fs-error]

This one. Looks good to me.

Rebased on top of upstream, fixed the few minor nits you pointed out and push to:

https://github.com/amir73il/man-pages/commits/fan-fs-error

Can you please apply?

Quoted 1 line

Quoted 1 line

And I have more changes for upcoming v5.19... >

I have a question for you regarding new UAPI, such as FAN_MARK_EVICTABLE that got merged to v5.19-rc1.

Often, Michael would not want to merge UAPI changes to man pages before .0 release, because UAPI changes could be reverted before final release (which happened for fanotify).

I still want to post those man page patches for review early,

but don't want to mess up your patch review process. > I guess if I post them as [RFC] it will be a good sign for you not to merge them until the .0 release?
Should I simply use the subject "Fanotify updated for v5.19"?

Do you have a different view on the matter?
Don't care at all? ;-)