* [PATCH 1/2] fanotify_init.2, fanotify_mark.2: Document unprivileged listener
2021-03-18 16:08 [PATCH 0/2] fanotify man page updates for v5.13 Amir Goldstein
@ 2021-03-18 16:08 ` Amir Goldstein
2021-03-18 16:08 ` [PATCH 2/2] fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits Amir Goldstein
` (2 subsequent siblings)
3 siblings, 0 replies; 6+ messages in thread
From: Amir Goldstein @ 2021-03-18 16:08 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: Jan Kara, Matthew Bobrowski, linux-man
From: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Document the limited fanotify functionality that will be available for
unprivileged users from kernel v5.13.
Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
man2/fanotify_init.2 | 77 +++++++++++++++++++++++++++++++++++++-------
man2/fanotify_mark.2 | 9 ++++++
2 files changed, 74 insertions(+), 12 deletions(-)
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index ff656f438..5f54a8506 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -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
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index d5dcecc74..1bd0a30ea 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -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
--
2.25.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH 2/2] fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits
2021-03-18 16:08 [PATCH 0/2] fanotify man page updates for v5.13 Amir Goldstein
2021-03-18 16:08 ` [PATCH 1/2] fanotify_init.2, fanotify_mark.2: Document unprivileged listener Amir Goldstein
@ 2021-03-18 16:08 ` Amir Goldstein
2021-03-19 10:25 ` [PATCH 0/2] fanotify man page updates for v5.13 Jan Kara
2021-07-13 16:34 ` Amir Goldstein
3 siblings, 0 replies; 6+ messages in thread
From: Amir Goldstein @ 2021-03-18 16:08 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: Jan Kara, Matthew Bobrowski, linux-man
Update documentation about the new configurable fanotify limits
that will be available from Linux kernel 5.13.
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---
man2/fanotify_init.2 | 22 ++++++++++++++++------
man2/fanotify_mark.2 | 5 ++++-
man7/fanotify.7 | 35 +++++++++++++++++++++++++++++++++--
3 files changed, 53 insertions(+), 9 deletions(-)
diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index 5f54a8506..d18c6b6b1 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -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.
diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2
index 1bd0a30ea..104f1c176 100644
--- a/man2/fanotify_mark.2
+++ b/man2/fanotify_mark.2
@@ -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
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 2785dd773..f62008374 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -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),
--
2.25.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] fanotify man page updates for v5.13
2021-03-18 16:08 [PATCH 0/2] fanotify man page updates for v5.13 Amir Goldstein
2021-03-18 16:08 ` [PATCH 1/2] fanotify_init.2, fanotify_mark.2: Document unprivileged listener Amir Goldstein
2021-03-18 16:08 ` [PATCH 2/2] fanotify_init.2, fanotify_mark.2, fanotify.7: Configurable limits Amir Goldstein
@ 2021-03-19 10:25 ` Jan Kara
2021-07-13 16:34 ` Amir Goldstein
3 siblings, 0 replies; 6+ messages in thread
From: Jan Kara @ 2021-03-19 10:25 UTC (permalink / raw)
To: Amir Goldstein; +Cc: Michael Kerrisk, Jan Kara, Matthew Bobrowski, linux-man
On Thu 18-03-21 18:08:15, Amir Goldstein wrote:
> 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:
Reviewed-by: Jan Kara <jack@suse.cz>
Honza
>
> Thanks,
> Amir.
>
> [1] https://lore.kernel.org/linux-fsdevel/20210304112921.3996419-1-amir73il@gmail.com/
>
> 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
>
--
Jan Kara <jack@suse.com>
SUSE Labs, CR
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] fanotify man page updates for v5.13
2021-03-18 16:08 [PATCH 0/2] fanotify man page updates for v5.13 Amir Goldstein
` (2 preceding siblings ...)
2021-03-19 10:25 ` [PATCH 0/2] fanotify man page updates for v5.13 Jan Kara
@ 2021-07-13 16:34 ` Amir Goldstein
2021-09-02 4:53 ` Amir Goldstein
3 siblings, 1 reply; 6+ messages in thread
From: Amir Goldstein @ 2021-07-13 16:34 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: Jan Kara, Matthew Bobrowski, linux-man
On Thu, Mar 18, 2021 at 6:08 PM Amir Goldstein <amir73il@gmail.com> wrote:
>
> 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.
>
> [1] https://lore.kernel.org/linux-fsdevel/20210304112921.3996419-1-amir73il@gmail.com/
>
> 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
>
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH 0/2] fanotify man page updates for v5.13
2021-07-13 16:34 ` Amir Goldstein
@ 2021-09-02 4:53 ` Amir Goldstein
0 siblings, 0 replies; 6+ messages in thread
From: Amir Goldstein @ 2021-09-02 4:53 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: Jan Kara, Matthew Bobrowski, linux-man
On Tue, Jul 13, 2021 at 7:34 PM Amir Goldstein <amir73il@gmail.com> wrote:
>
> On Thu, Mar 18, 2021 at 6:08 PM Amir Goldstein <amir73il@gmail.com> wrote:
> >
> > 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.
>
Hi Michael,
Did you miss these updates for 5.13?
Thanks,
Amir.
>
> >
> > [1] https://lore.kernel.org/linux-fsdevel/20210304112921.3996419-1-amir73il@gmail.com/
> >
> > 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
> >
^ permalink raw reply [flat|nested] 6+ messages in thread