| Message ID | 20250331135101.1436770-1-amir73il@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | fanotify: Document mount namespace events | expand |
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
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.
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
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.
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.
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!
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
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(-)