[PATCH 0/2] fanotify man page updates for v5.13

[PATCH 0/2] fanotify man page updates for v5.13

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

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

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

[Amir Goldstein]

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

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

[Amir Goldstein]

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

Re: [PATCH 0/2] fanotify man page updates for v5.13

[Jan Kara]

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

Re: [PATCH 0/2] fanotify man page updates for v5.13

[Amir Goldstein]

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
>

Re: [PATCH 0/2] fanotify man page updates for v5.13

[Amir Goldstein]

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