Merge tag 'fsnotify_for_v5.16-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/jack/linux-fs

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

   edid

   efi-stub

   ext4

   filesystem-monitoring

   nfs/index

   gpio/index

   highuid

#include <linux/part_stat.h>

#include <linux/kthread.h>

#include <linux/freezer.h>

#include <linux/fsnotify.h>

#include "ext4.h"

#include "ext4_extents.h"	/* Needed for trace points definition */

		       sb->s_id, function, line, current->comm, &vaf);

		va_end(args);

	}

	fsnotify_sb_error(sb, NULL, error ? error : EFSCORRUPTED);

	ext4_handle_error(sb, force_ro, error, 0, block, function, line);

}

			       current->comm, &vaf);

		va_end(args);

	}

	fsnotify_sb_error(inode->i_sb, inode, error ? error : EFSCORRUPTED);

	ext4_handle_error(inode->i_sb, false, error, inode->i_ino, block,

			  function, line);

}

			       current->comm, path, &vaf);

		va_end(args);

	}

	fsnotify_sb_error(inode->i_sb, inode, EFSCORRUPTED);

	ext4_handle_error(inode->i_sb, false, EFSCORRUPTED, inode->i_ino, block,

			  function, line);

}

		printk(KERN_CRIT "EXT4-fs error (device %s) in %s:%d: %s\n",

		       sb->s_id, function, line, errstr);

	}

	fsnotify_sb_error(sb, NULL, errno ? errno : EFSCORRUPTED);

	ext4_handle_error(sb, false, -errno, 0, 0, function, line);

}

				struct inode *inode, struct inode *dir,

				const struct qstr *name, u32 cookie)

{

	if (WARN_ON_ONCE(!inode))

		return 0;

	trace_nfsd_file_fsnotify_handle_event(inode, mask);

	/* Should be no marks on non-regular files */

	return fanotify_info_equal(info1, info2);

}

static bool fanotify_error_event_equal(struct fanotify_error_event *fee1,

				       struct fanotify_error_event *fee2)

{

	/* Error events against the same file system are always merged. */

	if (!fanotify_fsid_equal(&fee1->fsid, &fee2->fsid))

		return false;

	return true;

}

static bool fanotify_should_merge(struct fanotify_event *old,

				  struct fanotify_event *new)

{

	case FANOTIFY_EVENT_TYPE_FID_NAME:

		return fanotify_name_event_equal(FANOTIFY_NE(old),

						 FANOTIFY_NE(new));

	case FANOTIFY_EVENT_TYPE_FS_ERROR:

		return fanotify_error_event_equal(FANOTIFY_EE(old),

						  FANOTIFY_EE(new));

	default:

		WARN_ON_ONCE(1);

	}

			break;

		if (fanotify_should_merge(old, new)) {

			old->mask |= new->mask;

			if (fanotify_is_error_event(old->mask))

				FANOTIFY_EE(old)->err_count++;

			return 1;

		}

	}

static int fanotify_encode_fh_len(struct inode *inode)

{

	int dwords = 0;

	int fh_len;

	if (!inode)

		return 0;

	exportfs_encode_inode_fh(inode, NULL, &dwords, NULL);

	fh_len = dwords << 2;

	/*

	 * struct fanotify_error_event might be preallocated and is

	 * limited to MAX_HANDLE_SZ.  This should never happen, but

	 * safeguard by forcing an invalid file handle.

	 */

	if (WARN_ON_ONCE(fh_len > MAX_HANDLE_SZ))

		return 0;

	return dwords << 2;

	return fh_len;

}

/*

	fh->type = FILEID_ROOT;

	fh->len = 0;

	fh->flags = 0;

	/*

	 * Invalid FHs are used by FAN_FS_ERROR for errors not

	 * linked to any inode. The f_handle won't be reported

	 * back to userspace.

	 */

	if (!inode)

		return 0;

		goto out;

	/*

	 * !gpf means preallocated variable size fh, but fh_len could

	fh->type = type;

	fh->len = fh_len;

	/* Mix fh into event merge key */

out:

	/*

	 * Mix fh into event merge key.  Hash might be NULL in case of

	 * unhashed FID events (i.e. FAN_FS_ERROR).

	 */

	if (hash)

		*hash ^= fanotify_hash_fh(fh);

	return FANOTIFY_FH_HDR_LEN + fh_len;

	if (event_mask & ALL_FSNOTIFY_DIRENT_EVENTS)

		return dir;

	if (S_ISDIR(inode->i_mode))

	if (inode && S_ISDIR(inode->i_mode))

		return inode;

	return dir;

	return &fne->fae;

}

static struct fanotify_event *fanotify_alloc_error_event(

						struct fsnotify_group *group,

						__kernel_fsid_t *fsid,

						const void *data, int data_type,

						unsigned int *hash)

{

	struct fs_error_report *report =

			fsnotify_data_error_report(data, data_type);

	struct inode *inode;

	struct fanotify_error_event *fee;

	int fh_len;

	if (WARN_ON_ONCE(!report))

		return NULL;

	fee = mempool_alloc(&group->fanotify_data.error_events_pool, GFP_NOFS);

	if (!fee)

		return NULL;

	fee->fae.type = FANOTIFY_EVENT_TYPE_FS_ERROR;

	fee->error = report->error;

	fee->err_count = 1;

	fee->fsid = *fsid;

	inode = report->inode;

	fh_len = fanotify_encode_fh_len(inode);

	/* Bad fh_len. Fallback to using an invalid fh. Should never happen. */

	if (!fh_len && inode)

		inode = NULL;

	fanotify_encode_fh(&fee->object_fh, inode, fh_len, NULL, 0);

	*hash ^= fanotify_hash_fsid(fsid);

	return &fee->fae;

}

static struct fanotify_event *fanotify_alloc_event(struct fsnotify_group *group,

						   u32 mask, const void *data,

						   int data_type, struct inode *dir,

	if (fanotify_is_perm_event(mask)) {

		event = fanotify_alloc_perm_event(path, gfp);

	} else if (fanotify_is_error_event(mask)) {

		event = fanotify_alloc_error_event(group, fsid, data,

						   data_type, &hash);

	} else if (name_event && (file_name || child)) {

		event = fanotify_alloc_name_event(id, fsid, file_name, child,

						  &hash, gfp);

	assert_spin_locked(&group->notification_lock);

	if (!fanotify_is_hashed_event(event->mask))

		return;

	pr_debug("%s: group=%p event=%p bucket=%u\n", __func__,

		 group, event, bucket);

	BUILD_BUG_ON(FAN_ONDIR != FS_ISDIR);

	BUILD_BUG_ON(FAN_OPEN_EXEC != FS_OPEN_EXEC);

	BUILD_BUG_ON(FAN_OPEN_EXEC_PERM != FS_OPEN_EXEC_PERM);

	BUILD_BUG_ON(FAN_FS_ERROR != FS_ERROR);

	BUILD_BUG_ON(HWEIGHT32(ALL_FANOTIFY_EVENT_BITS) != 19);

	BUILD_BUG_ON(HWEIGHT32(ALL_FANOTIFY_EVENT_BITS) != 20);

	mask = fanotify_group_event_mask(group, iter_info, mask, data,

					 data_type, dir);

	}

	fsn_event = &event->fse;

	ret = fsnotify_add_event(group, fsn_event, fanotify_merge,

				 fanotify_is_hashed_event(mask) ?

				 fanotify_insert_event : NULL);

	ret = fsnotify_insert_event(group, fsn_event, fanotify_merge,

				    fanotify_insert_event);

	if (ret) {

		/* Permission events shouldn't be merged */

		BUG_ON(ret == 1 && mask & FANOTIFY_PERM_EVENTS);

	if (group->fanotify_data.ucounts)

		dec_ucount(group->fanotify_data.ucounts,

			   UCOUNT_FANOTIFY_GROUPS);

	if (mempool_initialized(&group->fanotify_data.error_events_pool))

		mempool_exit(&group->fanotify_data.error_events_pool);

}

static void fanotify_free_path_event(struct fanotify_event *event)

	kfree(FANOTIFY_NE(event));

}

static void fanotify_free_event(struct fsnotify_event *fsn_event)

static void fanotify_free_error_event(struct fsnotify_group *group,

				      struct fanotify_event *event)

{

	struct fanotify_error_event *fee = FANOTIFY_EE(event);

	mempool_free(fee, &group->fanotify_data.error_events_pool);

}

static void fanotify_free_event(struct fsnotify_group *group,

				struct fsnotify_event *fsn_event)

{

	struct fanotify_event *event;

	case FANOTIFY_EVENT_TYPE_OVERFLOW:

		kfree(event);

		break;

	case FANOTIFY_EVENT_TYPE_FS_ERROR:

		fanotify_free_error_event(group, event);

		break;

	default:

		WARN_ON_ONCE(1);

	}