mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
78 lines
3.0 KiB
78 lines
3.0 KiB
.. SPDX-License-Identifier: GPL-2.0 |
|
|
|
==================================== |
|
File system Monitoring with fanotify |
|
==================================== |
|
|
|
File system Error Reporting |
|
=========================== |
|
|
|
Fanotify supports the FAN_FS_ERROR event type for file system-wide error |
|
reporting. It is meant to be used by file system health monitoring |
|
daemons, which listen for these events and take actions (notify |
|
sysadmin, start recovery) when a file system problem is detected. |
|
|
|
By design, a FAN_FS_ERROR notification exposes sufficient information |
|
for a monitoring tool to know a problem in the file system has happened. |
|
It doesn't necessarily provide a user space application with semantics |
|
to verify an IO operation was successfully executed. That is out of |
|
scope for this feature. Instead, it is only meant as a framework for |
|
early file system problem detection and reporting recovery tools. |
|
|
|
When a file system operation fails, it is common for dozens of kernel |
|
errors to cascade after the initial failure, hiding the original failure |
|
log, which is usually the most useful debug data to troubleshoot the |
|
problem. For this reason, FAN_FS_ERROR tries to report only the first |
|
error that occurred for a file system since the last notification, and |
|
it simply counts additional errors. This ensures that the most |
|
important pieces of information are never lost. |
|
|
|
FAN_FS_ERROR requires the fanotify group to be setup with the |
|
FAN_REPORT_FID flag. |
|
|
|
At the time of this writing, the only file system that emits FAN_FS_ERROR |
|
notifications is Ext4. |
|
|
|
A FAN_FS_ERROR Notification has the following format:: |
|
|
|
:: |
|
|
|
[ Notification Metadata (Mandatory) ] |
|
[ Generic Error Record (Mandatory) ] |
|
[ FID record (Mandatory) ] |
|
|
|
The order of records is not guaranteed, and new records might be added |
|
in the future. Therefore, applications must not rely on the order and |
|
must be prepared to skip over unknown records. Please refer to |
|
``samples/fanotify/fs-monitor.c`` for an example parser. |
|
|
|
Generic error record |
|
-------------------- |
|
|
|
The generic error record provides enough information for a file system |
|
agnostic tool to learn about a problem in the file system, without |
|
providing any additional details about the problem. This record is |
|
identified by ``struct fanotify_event_info_header.info_type`` being set |
|
to FAN_EVENT_INFO_TYPE_ERROR. |
|
|
|
:: |
|
|
|
struct fanotify_event_info_error { |
|
struct fanotify_event_info_header hdr; |
|
__s32 error; |
|
__u32 error_count; |
|
}; |
|
|
|
The `error` field identifies the type of error using errno values. |
|
`error_count` tracks the number of errors that occurred and were |
|
suppressed to preserve the original error information, since the last |
|
notification. |
|
|
|
FID record |
|
---------- |
|
|
|
The FID record can be used to uniquely identify the inode that triggered |
|
the error through the combination of fsid and file handle. A file system |
|
specific application can use that information to attempt a recovery |
|
procedure. Errors that are not related to an inode are reported with an |
|
empty file handle of type FILEID_INVALID.
|
|
|