[PATCH] fanotify: Document mount namespace events

[PATCH] fanotify: Document mount namespace events

[Amir Goldstein]

Used to subscribe for notifications for when mounts
are attached/detached from a mount namespace.

Cc: Jan Kara <jack@suse.cz>
Cc: Miklos Szeredi <mszeredi@redhat.com>
Cc: Christian Brauner <brauner@kernel.org>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Alejandro,

This feature was also added (by Miklos) in v6.14.

The man page patch can be merged independently of the
FAN_PRE_ACCESS patch.

However, this patch depends on the FAN_FS_ERROR cleanup patch
that I just posted, because of the reordering of event entries.

Thanks,
Amir.

 man/man2/fanotify_init.2 | 20 ++++++++++++++++++++
 man/man2/fanotify_mark.2 | 35 ++++++++++++++++++++++++++++++++++-
 man/man7/fanotify.7      | 39 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 93 insertions(+), 1 deletion(-)

diff --git a/man/man2/fanotify_init.2 b/man/man2/fanotify_init.2
index 699b6f054..26289c496 100644
--- a/man/man2/fanotify_init.2
+++ b/man/man2/fanotify_init.2
@@ -330,6 +330,26 @@ that the directory entry is referring to.
 This is a synonym for
 .RB ( FAN_REPORT_DFID_NAME | FAN_REPORT_FID | FAN_REPORT_TARGET_FID ).
 .TP
+.BR FAN_REPORT_MNT " (since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+This value allows the receipt of events which contain additional information
+about the underlying mount correlated to an event.
+An additional record of type
+.B FAN_EVENT_INFO_TYPE_MNT
+encapsulates the information about the mount and is included alongside the
+generic event metadata structure.
+The use of
+.BR FAN_CLASS_CONTENT ,
+.BR FAN_CLASS_PRE_CONTENT,
+or any of the
+.B FAN_REPORT_DFID_NAME_TARGET
+flags along with this flag is not permitted
+and will result in the error
+.BR EINVAL .
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .BR FAN_REPORT_PIDFD " (since Linux 5.15 and 5.10.220)"
 .\" commit af579beb666aefb17e9a335c12c788c92932baf1
 Events for fanotify groups initialized with this flag will contain
diff --git a/man/man2/fanotify_mark.2 b/man/man2/fanotify_mark.2
index da569279b..b843c1f9a 100644
--- a/man/man2/fanotify_mark.2
+++ b/man/man2/fanotify_mark.2
@@ -67,7 +67,8 @@ contains
 all marks for filesystems are removed from the group.
 Otherwise, all marks for directories and files are removed.
 No flag other than, and at most one of, the flags
-.B FAN_MARK_MOUNT
+.BR FAN_MARK_MNTNS ,
+.BR FAN_MARK_MOUNT ,
 or
 .B FAN_MARK_FILESYSTEM
 can be used in conjunction with
@@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
 .B ENOTDIR
 shall be raised.
 .TP
+.BR FAN_MARK_MNTNS " (since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+Mark the mount namespace of the path specified by
+.IR pathname .
+If
+.I pathname
+is not itself a mount point,
+the mount namespace of the mount containing
+.I pathname
+will be marked.
+An fanotify group that is initialized with flag
+.B FAN_REPORT_MNT
+is required.
+.TP
 .B FAN_MARK_MOUNT
 Mark the mount specified by
 .IR pathname .
@@ -395,6 +410,24 @@ Create an event when a marked file or directory itself has been moved.
 An fanotify group that identifies filesystem objects by file handles
 is required.
 .TP
+.BR FAN_MNT_ATTACH ", " FAN_MNT_DETACH " (since Linux 6.14)"
+.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
+Create an event when a mount was attached to or detached from a marked mount namespace.
+An attempt to set this flag on an inode, mount or filesystem mark
+will result in the error
+.BR EINVAL .
+An fanotify group that is initialized with flag
+.B FAN_REPORT_MNT
+and the mark flag
+.B FAN_MARK_MNTNS
+are required.
+An additional information record of type
+.B FAN_EVENT_INFO_TYPE_MNT
+is returned with the event.
+See
+.BR fanotify (7)
+for additional details.
+.TP
 .BR FAN_FS_ERROR " (since Linux 5.16, 5.15.154, and 5.10.220)"
 .\" commit 9709bd548f11a092d124698118013f66e1740f9b
 Create an event when a filesystem error
diff --git a/man/man7/fanotify.7 b/man/man7/fanotify.7
index 77dcb8aa5..98705c3c7 100644
--- a/man/man7/fanotify.7
+++ b/man/man7/fanotify.7
@@ -228,6 +228,23 @@ struct fanotify_event_info_pidfd {
 .EE
 .in
 .P
+In cases where an fanotify group is initialized with
+.BR FAN_REPORT_MNT ,
+event listeners should expect to receive the below
+information record object alongside the generic
+.I fanotify_event_metadata
+structure within the read buffer.
+This structure is defined as follows:
+.P
+.in +4n
+.EX
+struct fanotify_event_info_mnt {
+    struct fanotify_event_info_header hdr;
+    __u64 mnt_id;
+};
+.EE
+.in
+.P
 In case of a
 .B FAN_FS_ERROR
 event,
@@ -442,6 +459,12 @@ A file or directory that was opened read-only
 .RB ( O_RDONLY )
 was closed.
 .TP
+.BR FAN_MNT_ATTACH
+A mount was attached to mount namespace.
+.TP
+.BR FAN_MNT_DETACH
+A mount was detached to mount namespace.
+.TP
 .B FAN_FS_ERROR
 A filesystem error was detected.
 .TP
@@ -540,6 +563,7 @@ The value of this field can be set to one of the following:
 .BR FAN_EVENT_INFO_TYPE_FID ,
 .BR FAN_EVENT_INFO_TYPE_DFID ,
 .BR FAN_EVENT_INFO_TYPE_DFID_NAME ,
+.BR FAN_EVENT_INFO_TYPE_MNT ,
 .BR FAN_EVENT_INFO_TYPE_ERROR ,
 .BR FAN_EVENT_INFO_TYPE_RANGE ,
 or
@@ -727,6 +751,21 @@ in case of a terminated process, the value will be
 .BR \-ESRCH .
 .P
 The fields of the
+.I fanotify_event_info_mnt
+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_MNT .
+.TP
+.I .mnt_id
+Identifies the mount associated with the event.
+.P
+The fields of the
 .I fanotify_event_info_error
 structure are as follows:
 .TP
-- 
2.34.1

Re: [PATCH] fanotify: Document mount namespace events

[Jan Kara]

On Mon 31-03-25 15:51:01, Amir Goldstein wrote:
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
> 
> Cc: Jan Kara <jack@suse.cz>
> Cc: Miklos Szeredi <mszeredi@redhat.com>
> Cc: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
...
> @@ -442,6 +459,12 @@ A file or directory that was opened read-only
>  .RB ( O_RDONLY )
>  was closed.
>  .TP
> +.BR FAN_MNT_ATTACH
> +A mount was attached to mount namespace.
> +.TP
> +.BR FAN_MNT_DETACH
> +A mount was detached to mount namespace.
			^^ from

> @@ -727,6 +751,21 @@ in case of a terminated process, the value will be
>  .BR \-ESRCH .
>  .P
>  The fields of the
> +.I fanotify_event_info_mnt
> +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_MNT .
> +.TP
> +.I .mnt_id
> +Identifies the mount associated with the event.

Since mnt_id is not well established, I think we should tell here a bit
more about the mnt_id - that this is the ID you'll get from listmount(2)
and can use it e.g. with statmount(2).

								Honza
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Re: [PATCH] fanotify: Document mount namespace events

[Amir Goldstein]

On Mon, Mar 31, 2025 at 4:03 PM Jan Kara <jack@suse.cz> wrote:
>
> On Mon 31-03-25 15:51:01, Amir Goldstein wrote:
> > Used to subscribe for notifications for when mounts
> > are attached/detached from a mount namespace.
> >
> > Cc: Jan Kara <jack@suse.cz>
> > Cc: Miklos Szeredi <mszeredi@redhat.com>
> > Cc: Christian Brauner <brauner@kernel.org>
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ...
> > @@ -442,6 +459,12 @@ A file or directory that was opened read-only
> >  .RB ( O_RDONLY )
> >  was closed.
> >  .TP
> > +.BR FAN_MNT_ATTACH
> > +A mount was attached to mount namespace.
> > +.TP
> > +.BR FAN_MNT_DETACH
> > +A mount was detached to mount namespace.
>                         ^^ from
>

thanks for spotting

> > @@ -727,6 +751,21 @@ in case of a terminated process, the value will be
> >  .BR \-ESRCH .
> >  .P
> >  The fields of the
> > +.I fanotify_event_info_mnt
> > +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_MNT .
> > +.TP
> > +.I .mnt_id
> > +Identifies the mount associated with the event.
>
> Since mnt_id is not well established, I think we should tell here a bit
> more about the mnt_id - that this is the ID you'll get from listmount(2)
> and can use it e.g. with statmount(2).

You are right, but it is actually established much sooner,
As I described mount_id in the recently merged man page patch
name_to_handle_at.2: Document the AT_HANDLE_MNT_ID_UNIQUE flag

...is the unique mount id as the one returned by
.BR statx (2)
with the
.BR STATX_MNT_ID_UNIQUE
flag.

So I will add a reference to statx here as well.

Thanks,
Amir.

Re: [PATCH] fanotify: Document mount namespace events

[Miklos Szeredi]

On Mon, 31 Mar 2025 at 15:51, Amir Goldstein <amir73il@gmail.com> wrote:

> @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
>  .B ENOTDIR
>  shall be raised.
>  .TP
> +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> +Mark the mount namespace of the path specified by
> +.IR pathname .
> +If
> +.I pathname
> +is not itself a mount point,
> +the mount namespace of the mount containing
> +.I pathname
> +will be marked.

This was the original version, but it was changed to take an nsfs path
(/proc/$PID/ns/mnt) instead.

Looks good otherwise.  Thanks for working on this!

Miklos

Re: [PATCH] fanotify: Document mount namespace events

[Amir Goldstein]

On Mon, Mar 31, 2025 at 4:37 PM Miklos Szeredi <miklos@szeredi.hu> wrote:
>
> On Mon, 31 Mar 2025 at 15:51, Amir Goldstein <amir73il@gmail.com> wrote:
>
> > @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
> >  .B ENOTDIR
> >  shall be raised.
> >  .TP
> > +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > +Mark the mount namespace of the path specified by
> > +.IR pathname .
> > +If
> > +.I pathname
> > +is not itself a mount point,
> > +the mount namespace of the mount containing
> > +.I pathname
> > +will be marked.
>
> This was the original version, but it was changed to take an nsfs path
> (/proc/$PID/ns/mnt) instead.

Oh right :)

Thanks,
Amir.

Re: [PATCH] fanotify: Document mount namespace events

[Amir Goldstein]

On Mon, Mar 31, 2025 at 4:49 PM Amir Goldstein <amir73il@gmail.com> wrote:
>
> On Mon, Mar 31, 2025 at 4:37 PM Miklos Szeredi <miklos@szeredi.hu> wrote:
> >
> > On Mon, 31 Mar 2025 at 15:51, Amir Goldstein <amir73il@gmail.com> wrote:
> >
> > > @@ -99,6 +100,20 @@ If the filesystem object to be marked is not a directory, the error
> > >  .B ENOTDIR
> > >  shall be raised.
> > >  .TP
> > > +.BR FAN_MARK_MNTNS " (since Linux 6.14)"
> > > +.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
> > > +Mark the mount namespace of the path specified by
> > > +.IR pathname .
> > > +If
> > > +.I pathname
> > > +is not itself a mount point,
> > > +the mount namespace of the mount containing
> > > +.I pathname
> > > +will be marked.
> >
> > This was the original version, but it was changed to take an nsfs path
> > (/proc/$PID/ns/mnt) instead.
>

Revised as:

.BR FAN_MARK_MNTNS " (since Linux 6.14)"
.\" commit 0f46d81f2bce970b1c562aa3c944a271bbec2729
Mark the mount namespace specified by
.IR pathname .
If the
.I pathname
is not a path that represents a mount namespace (e.g.
.BR /proc/ pid /ns/mnt ),
the call fails with the error
.BR EINVAL .
An fanotify group that is initialized with flag
.B FAN_REPORT_MNT
is required.
.TP

Thanks,
Amir.

Re: [PATCH] fanotify: Document mount namespace events

[Christian Brauner]

On Mon, Mar 31, 2025 at 03:51:01PM +0200, Amir Goldstein wrote:
> Used to subscribe for notifications for when mounts
> are attached/detached from a mount namespace.
> 
> Cc: Jan Kara <jack@suse.cz>
> Cc: Miklos Szeredi <mszeredi@redhat.com>
> Cc: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---

With the changes pointed out by Miklos and Jan:

Reviewed-by: Christian Brauner <brauner@kernel.org>

Thanks for doing this!