Skip to contentSkip to conversation

fanotify man page updates for v5.13

PATCH Superseded Amir Goldstein 2 participants 6 messages Mar 18, 2021 – Sep 2, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover fanotify man page updates for v5.13

Hi Michael,

Following are updated for changes queued for v5.13 [1]:
- Unprivileged fanotify listener
- Configurable limits

It is still pretty early in the development cycle, but I am posting them early for review.

Thanks,
Amir.

[1] https://lore.kernel.org/linux-fsdevel/[email protected]/

Amir Goldstein (1):
fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits

Matthew Bobrowski (1):
fanotify_init.2, fanotify_mark.2: Document unprivileged listener

 man2/fanotify_init.2 | 99 ++++++++++++++++++++++++++++++++++++--------
 man2/fanotify_mark.2 | 14 ++++++-
 man7/fanotify.7      | 35 +++++++++++++++-
 3 files changed, 127 insertions(+), 21 deletions(-)
Signature · 1 line
2.25.1
#1 lore raw

PATCH 1/2 fanotify_init.2, fanotify_mark.2: Document unprivileged listener

From: Matthew Bobrowski <[email protected]>

Document the limited fanotify functionality that will be available for unprivileged users from kernel v5.13.

---
 man2/fanotify_init.2 | 77 +++++++++++++++++++++++++++++++++++++-------
 man2/fanotify_mark.2 |  9 ++++++
 2 files changed, 74 insertions(+), 12 deletions(-)
man2/fanotify_init.2 +65 -12
index ff656f438..5f54a8506 100644
@@ -57,15 +57,6 @@ In the current implementation, the number of fanotify groups per user is
 limited to 128.
 This limit cannot be overridden.
 .PP
-Calling
-.BR fanotify_init ()
-requires the
-.B CAP_SYS_ADMIN
-capability.
-This constraint might be relaxed in future versions of the API.
-Therefore, certain additional capability checks have been implemented as
-indicated below.
-.PP
 The
 .I flags
 argument contains a multi-bit field defining the notification class of the
@@ -86,6 +77,9 @@ It is intended for event listeners that need to access files before they
 contain their final data.
 This notification class might be used by hierarchical storage managers,
 for example.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B FAN_CLASS_CONTENT
 This value allows the receipt of events notifying that a file has been
@@ -94,6 +88,9 @@ It is intended for event listeners that need to access files when they
 already contain their final content.
 This notification class might be used by malware detection programs, for
 example.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B FAN_CLASS_NOTIF
 This is the default value.
@@ -155,6 +152,9 @@ supplied to
 .BR read (2)
 (see
 .BR fanotify (7)).
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
 .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
@@ -163,6 +163,9 @@ permission events.
 The permission event response has to be marked with the
 .B FAN_AUDIT
 flag for an audit log record to be generated.
+Use of this flag requires the
+.B CAP_AUDIT_WRITE
+capability.
 .TP
 .BR FAN_REPORT_FID " (since Linux 5.1)"
 .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
@@ -378,13 +381,63 @@ The fanotify API is available only if the kernel was configured with
 .BR CONFIG_FANOTIFY .
 .TP
 .B EPERM
-The operation is not permitted because the caller lacks the
-.B CAP_SYS_ADMIN
-capability.
+The operation is not permitted because the caller lacks a required capability.
 .SH VERSIONS
 .BR fanotify_init ()
 was introduced in version 2.6.36 of the Linux kernel and enabled in version
 2.6.37.
+.PP
+Prior to Linux 5.13,
+.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
+calling
+.BR fanotify_init ()
+required the
+.B CAP_SYS_ADMIN
+capability.
+Since Linux 5.13,
+.\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7
+users may call
+.BR fanotify_init ()
+without the
+.B CAP_SYS_ADMIN
+capability to create and intialize an fanotify group with limited functionality.
+.TP
+The limitations imposed on an event listener created by a user without the
+.B CAP_SYS_ADMIN
+capability are as follows:
+.RS
+.IP * 3
+The user cannot request for an unlimited event queue by using
+.BR FAN_UNLIMITED_QUEUE .
+.IP * 3
+The user cannot request for an unlimited number of marks by using
+.BR FAN_UNLIMITED_MARKS .
+.IP * 3
+The user cannot request to use either notification classes
+.BR FAN_CLASS_CONTENT
+or
+.BR FAN_CLASS_PRE_CONTENT .
+This means that user cannot request permission events.
+.IP * 3
+The user is required to create a group that identifies filesystem objects by
+file handles, for example, by providing the
+.BR FAN_REPORT_FID
+flag.
+.IP * 3
+The user is limited to only mark inodes.
+The ability to mark a mount or filesystem via
+.BR fanotify_mark()
+through the use of
+.BR FAN_MARK_MOUNT
+or
+.BR FAN_MARK_FILESYSTEM
+is not permitted.
+.IP * 3
+The event object in the event queue is limited in terms of the information
+that is made available to the unprivileged user.
+A user will also not receive the pid that generated the event, unless the
+listening process itself generated the event.
+.RE
 .SH CONFORMING TO
 This system call is Linux-specific.
 .SH BUGS
man2/fanotify_mark.2 +9 -0
index d5dcecc74..1bd0a30ea 100644
@@ -142,6 +142,9 @@ contains
 Attempting to do so will result in the error
 .B EINVAL
 being returned.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
@@ -152,6 +155,9 @@ The filesystem containing
 will be marked.
 All the contained files and directories of the filesystem from any mount
 point will be monitored.
+Use of this flag requires the
+.B CAP_SYS_ADMIN
+capability.
 .TP
 .B FAN_MARK_IGNORED_MASK
 The events in
@@ -441,6 +447,9 @@ handles.
 This error can be returned only with an fanotify group that identifies
 filesystem objects by file handles.
 .TP
+.B EPERM
+The operation is not permitted because the caller lacks a required capability.
+.TP
 .B EXDEV
 The filesystem object indicated by
 .I pathname
Signature · 1 line
2.25.1
#2 lore raw

PATCH 2/2 fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits

In reply to Amir Goldstein

Update documentation about the new configurable fanotify limits that will be available from Linux kernel 5.13.

---
 man2/fanotify_init.2 | 22 ++++++++++++++++------
 man2/fanotify_mark.2 |  5 ++++-
 man7/fanotify.7      | 35 +++++++++++++++++++++++++++++++++--
 3 files changed, 53 insertions(+), 9 deletions(-)
man2/fanotify_init.2 +16 -6
index 5f54a8506..d18c6b6b1 100644
@@ -53,9 +53,10 @@ descriptor.
 Multiple programs may be using the fanotify interface at the same time to
 monitor the same files.
 .PP
-In the current implementation, the number of fanotify groups per user is
-limited to 128.
-This limit cannot be overridden.
+The number of fanotify groups per user is limited.
+See
+.BR fanotify (7)
+for details about this limit.
 .PP
 The
 .I flags
@@ -130,13 +131,19 @@ fails with the error
 .BR EAGAIN .
 .TP
 .B FAN_UNLIMITED_QUEUE
-Remove the limit of 16384 events for the event queue.
+Remove the limit on the number of events in the event queue.
+See
+.BR fanotify (7)
+for details about this limit.
 Use of this flag requires the
 .B CAP_SYS_ADMIN
 capability.
 .TP
 .B FAN_UNLIMITED_MARKS
-Remove the limit of 8192 marks.
+Remove the limit on the number of fanotify marks per user.
+See
+.BR fanotify (7)
+for details about this limit.
 Use of this flag requires the
 .B CAP_SYS_ADMIN
 capability.
@@ -366,7 +373,10 @@ defines all allowable bits for
 .IR flags .
 .TP
 .B EMFILE
-The number of fanotify groups for this user exceeds 128.
+The number of fanotify groups for this user exceeds the limit.
+See
+.BR fanotify (7)
+for details about this limit.
 .TP
 .B EMFILE
 The per-process limit on the number of open file descriptors has been reached.
man2/fanotify_mark.2 +4 -1
index 1bd0a30ea..104f1c176 100644
@@ -418,10 +418,13 @@ which is not marked.
 The necessary memory could not be allocated.
 .TP
 .B ENOSPC
-The number of marks exceeds the limit of 8192 and the
+The number of marks for this user exceeds the limit and the
 .B FAN_UNLIMITED_MARKS
 flag was not specified when the fanotify file descriptor was created with
 .BR fanotify_init (2).
+See
+.BR fanotify (7)
+for details about this limit.
 .TP
 .B ENOSYS
 This kernel does not implement
man7/fanotify.7 +33 -2
index 2785dd773..f62008374 100644
@@ -336,7 +336,7 @@ A file or directory that was opened read-only
 was closed.
 .TP
 .B FAN_Q_OVERFLOW
-The event queue exceeded the limit of 16384 entries.
+The event queue exceeded the limit on number of events.
 This limit can be overridden by specifying the
 .BR FAN_UNLIMITED_QUEUE
 flag when calling
@@ -606,7 +606,7 @@ are freed for reuse by the kernel.
 Upon
 .BR close (2),
 outstanding permission events will be set to allowed.
-.SS /proc/[pid]/fdinfo
+.SS /proc interfaces
 The file
 .I /proc/[pid]/fdinfo/[fd]
 contains information about fanotify marks for file descriptor
@@ -616,6 +616,37 @@ of process
 See
 .BR proc (5)
 for details.
+.PP
+Since Linux 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the following interfaces can be used to control the amount of
+kernel resources consumed by fanotify:
+.TP
+.I /proc/sys/fs/fanotify/max_queued_events
+The value in this file is used when an application calls
+.BR fanotify_init (2)
+to set an upper limit on the number of events that can be
+queued to the corresponding fanotify group.
+Events in excess of this limit are dropped, but an
+.B FAN_Q_OVERFLOW
+event is always generated.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 16384 events.
+.TP
+.I /proc/sys/fs/fanotify/max_user_group
+This specifies an upper limit on the number of fanotify groups
+that can be created per real user ID.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 128 groups per user.
+.TP
+.I /proc/sys/fs/fanotify/max_user_marks
+This specifies an upper limit on the number of fanotify marks
+that can be created per real user ID.
+Prior to Linux kernel 5.13,
+.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
+the hardcoded limit was 8192 marks per group (not per user).
 .SH ERRORS
 In addition to the usual errors for
 .BR read (2),
Signature · 1 line
2.25.1
Reviewed-by on the v1 series
#3 lore raw
In reply to Amir Goldstein
Quoted 8 lines · Amir Goldstein

Hi Michael,

Following are updated for changes queued for v5.13 [1]:
- Unprivileged fanotify listener
- Configurable limits

It is still pretty early in the development cycle, but I am posting them early for review.

The manpage updates look good to me. Feel free to add:

Honza

Quoted 20 lines

Thanks,
Amir.

[1] https://lore.kernel.org/linux-fsdevel/[email protected]/

Amir Goldstein (1):
fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits

Matthew Bobrowski (1):
fanotify_init.2, fanotify_mark.2: Document unprivileged listener

 man2/fanotify_init.2 | 99 ++++++++++++++++++++++++++++++++++++--------
 man2/fanotify_mark.2 | 14 ++++++-
 man7/fanotify.7      | 35 +++++++++++++++-
 3 files changed, 127 insertions(+), 21 deletions(-)
Signature · 1 line
2.25.1
Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#4 lore raw
In reply to Amir Goldstein
Quoted 10 lines · Amir Goldstein

Hi Michael,

Following are updated for changes queued for v5.13 [1]:
- Unprivileged fanotify listener
- Configurable limits

It is still pretty early in the development cycle, but I am posting them early for review.

I Michael,

This post was a long time ago so following up on it now. FYI, the 2 patches are also available on
https://github.com/amir73il/man-pages/commits/fanotify_unpriv
along with another minor man page update.
I will post it separately soon.

Thanks,
Amir.

Quoted 17 lines

[1] https://lore.kernel.org/linux-fsdevel/[email protected]/

Amir Goldstein (1):
fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits

Matthew Bobrowski (1):
fanotify_init.2, fanotify_mark.2: Document unprivileged listener

 man2/fanotify_init.2 | 99 ++++++++++++++++++++++++++++++++++++--------
 man2/fanotify_mark.2 | 14 ++++++-
 man7/fanotify.7      | 35 +++++++++++++++-
 3 files changed, 127 insertions(+), 21 deletions(-)

--
2.25.1

#5 lore raw
Quoted 13 lines · Amir Goldstein
Quoted 10 lines · Amir Goldstein

Hi Michael,

Following are updated for changes queued for v5.13 [1]:
- Unprivileged fanotify listener
- Configurable limits

It is still pretty early in the development cycle, but I am posting them early for review.

Quoted 8 lines

I Michael,

This post was a long time ago so following up on it now. FYI, the 2 patches are also available on
https://github.com/amir73il/man-pages/commits/fanotify_unpriv
along with another minor man page update.
I will post it separately soon.

Hi Michael,

Did you miss these updates for 5.13?

Thanks,
Amir.

Quoted 18 lines
Quoted 18 lines

[1] https://lore.kernel.org/linux-fsdevel/[email protected]/

Amir Goldstein (1):
fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits

Matthew Bobrowski (1):
fanotify_init.2, fanotify_mark.2: Document unprivileged listener

 man2/fanotify_init.2 | 99 ++++++++++++++++++++++++++++++++++++--------
 man2/fanotify_mark.2 | 14 ++++++-
 man7/fanotify.7      | 35 +++++++++++++++-
 3 files changed, 127 insertions(+), 21 deletions(-)

--
2.25.1