1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ==================================== 3 ====================================
4 File system Monitoring with fanotify 4 File system Monitoring with fanotify
5 ==================================== 5 ====================================
6 6
7 File system Error Reporting 7 File system Error Reporting
8 =========================== 8 ===========================
9 9
10 Fanotify supports the FAN_FS_ERROR event type 10 Fanotify supports the FAN_FS_ERROR event type for file system-wide error
11 reporting. It is meant to be used by file sys 11 reporting. It is meant to be used by file system health monitoring
12 daemons, which listen for these events and tak 12 daemons, which listen for these events and take actions (notify
13 sysadmin, start recovery) when a file system p 13 sysadmin, start recovery) when a file system problem is detected.
14 14
15 By design, a FAN_FS_ERROR notification exposes 15 By design, a FAN_FS_ERROR notification exposes sufficient information
16 for a monitoring tool to know a problem in the 16 for a monitoring tool to know a problem in the file system has happened.
17 It doesn't necessarily provide a user space ap 17 It doesn't necessarily provide a user space application with semantics
18 to verify an IO operation was successfully exe 18 to verify an IO operation was successfully executed. That is out of
19 scope for this feature. Instead, it is only m 19 scope for this feature. Instead, it is only meant as a framework for
20 early file system problem detection and report 20 early file system problem detection and reporting recovery tools.
21 21
22 When a file system operation fails, it is comm 22 When a file system operation fails, it is common for dozens of kernel
23 errors to cascade after the initial failure, h 23 errors to cascade after the initial failure, hiding the original failure
24 log, which is usually the most useful debug da 24 log, which is usually the most useful debug data to troubleshoot the
25 problem. For this reason, FAN_FS_ERROR tries 25 problem. For this reason, FAN_FS_ERROR tries to report only the first
26 error that occurred for a file system since th 26 error that occurred for a file system since the last notification, and
27 it simply counts additional errors. This ensu 27 it simply counts additional errors. This ensures that the most
28 important pieces of information are never lost 28 important pieces of information are never lost.
29 29
30 FAN_FS_ERROR requires the fanotify group to be 30 FAN_FS_ERROR requires the fanotify group to be setup with the
31 FAN_REPORT_FID flag. 31 FAN_REPORT_FID flag.
32 32
33 At the time of this writing, the only file sys 33 At the time of this writing, the only file system that emits FAN_FS_ERROR
34 notifications is Ext4. 34 notifications is Ext4.
35 35
36 A FAN_FS_ERROR Notification has the following 36 A FAN_FS_ERROR Notification has the following format::
37 37
38 :: 38 ::
39 39
40 [ Notification Metadata (Mandatory) ] 40 [ Notification Metadata (Mandatory) ]
41 [ Generic Error Record (Mandatory) ] 41 [ Generic Error Record (Mandatory) ]
42 [ FID record (Mandatory) ] 42 [ FID record (Mandatory) ]
43 43
44 The order of records is not guaranteed, and ne 44 The order of records is not guaranteed, and new records might be added
45 in the future. Therefore, applications must n 45 in the future. Therefore, applications must not rely on the order and
46 must be prepared to skip over unknown records. 46 must be prepared to skip over unknown records. Please refer to
47 ``samples/fanotify/fs-monitor.c`` for an examp 47 ``samples/fanotify/fs-monitor.c`` for an example parser.
48 48
49 Generic error record 49 Generic error record
50 -------------------- 50 --------------------
51 51
52 The generic error record provides enough infor 52 The generic error record provides enough information for a file system
53 agnostic tool to learn about a problem in the 53 agnostic tool to learn about a problem in the file system, without
54 providing any additional details about the pro 54 providing any additional details about the problem. This record is
55 identified by ``struct fanotify_event_info_hea 55 identified by ``struct fanotify_event_info_header.info_type`` being set
56 to FAN_EVENT_INFO_TYPE_ERROR. 56 to FAN_EVENT_INFO_TYPE_ERROR.
57 57
58 :: 58 ::
59 59
60 struct fanotify_event_info_error { 60 struct fanotify_event_info_error {
61 struct fanotify_event_info_header hd 61 struct fanotify_event_info_header hdr;
62 __s32 error; 62 __s32 error;
63 __u32 error_count; 63 __u32 error_count;
64 }; 64 };
65 65
66 The `error` field identifies the type of error 66 The `error` field identifies the type of error using errno values.
67 `error_count` tracks the number of errors that 67 `error_count` tracks the number of errors that occurred and were
68 suppressed to preserve the original error info 68 suppressed to preserve the original error information, since the last
69 notification. 69 notification.
70 70
71 FID record 71 FID record
72 ---------- 72 ----------
73 73
74 The FID record can be used to uniquely identif 74 The FID record can be used to uniquely identify the inode that triggered
75 the error through the combination of fsid and 75 the error through the combination of fsid and file handle. A file system
76 specific application can use that information 76 specific application can use that information to attempt a recovery
77 procedure. Errors that are not related to an 77 procedure. Errors that are not related to an inode are reported with an
78 empty file handle of type FILEID_INVALID. 78 empty file handle of type FILEID_INVALID.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.