0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================================
0004 File system Monitoring with fanotify
0005 ====================================
0006
0007 File system Error Reporting
0008 ===========================
0009
0010 Fanotify supports the FAN_FS_ERROR event type for file system-wide error
0011 reporting. It is meant to be used by file system health monitoring
0012 daemons, which listen for these events and take actions (notify
0013 sysadmin, start recovery) when a file system problem is detected.
0014
0015 By design, a FAN_FS_ERROR notification exposes sufficient information
0016 for a monitoring tool to know a problem in the file system has happened.
0017 It doesn't necessarily provide a user space application with semantics
0018 to verify an IO operation was successfully executed. That is out of
0019 scope for this feature. Instead, it is only meant as a framework for
0020 early file system problem detection and reporting recovery tools.
0021
0022 When a file system operation fails, it is common for dozens of kernel
0023 errors to cascade after the initial failure, hiding the original failure
0024 log, which is usually the most useful debug data to troubleshoot the
0025 problem. For this reason, FAN_FS_ERROR tries to report only the first
0026 error that occurred for a file system since the last notification, and
0027 it simply counts additional errors. This ensures that the most
0028 important pieces of information are never lost.
0029
0030 FAN_FS_ERROR requires the fanotify group to be setup with the
0031 FAN_REPORT_FID flag.
0032
0033 At the time of this writing, the only file system that emits FAN_FS_ERROR
0034 notifications is Ext4.
0035
0036 A FAN_FS_ERROR Notification has the following format::
0037
0038 ::
0039
0040 [ Notification Metadata (Mandatory) ]
0041 [ Generic Error Record (Mandatory) ]
0042 [ FID record (Mandatory) ]
0043
0044 The order of records is not guaranteed, and new records might be added
0045 in the future. Therefore, applications must not rely on the order and
0046 must be prepared to skip over unknown records. Please refer to
0047 ``samples/fanotify/fs-monitor.c`` for an example parser.
0048
0049 Generic error record
0050 --------------------
0051
0052 The generic error record provides enough information for a file system
0053 agnostic tool to learn about a problem in the file system, without
0054 providing any additional details about the problem. This record is
0055 identified by ``struct fanotify_event_info_header.info_type`` being set
0056 to FAN_EVENT_INFO_TYPE_ERROR.
0057
0058 ::
0059
0060 struct fanotify_event_info_error {
0061 struct fanotify_event_info_header hdr;
0062 __s32 error;
0063 __u32 error_count;
0064 };
0065
0066 The `error` field identifies the type of error using errno values.
0067 `error_count` tracks the number of errors that occurred and were
0068 suppressed to preserve the original error information, since the last
0069 notification.
0070
0071 FID record
0072 ----------
0073
0074 The FID record can be used to uniquely identify the inode that triggered
0075 the error through the combination of fsid and file handle. A file system
0076 specific application can use that information to attempt a recovery
0077 procedure. Errors that are not related to an inode are reported with an
0078 empty file handle of type FILEID_INVALID.
