[PATCH] fanotify: Document FAN_AUDIT flag

[PATCH] fanotify: Document FAN_AUDIT flag

[Jan Kara]

Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.

Signed-off-by: Jan Kara <jack@suse.cz>
---
 man2/fanotify_init.2 | 7 +++++++
 man7/fanotify.7      | 9 ++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
Steve glanced over it from the audit side to check things are sane.

diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
index ca03b11dc98a..6becc7a680db 100644
--- a/man2/fanotify_init.2
+++ b/man2/fanotify_init.2
@@ -155,6 +155,13 @@ supplied to
 (see
 .BR fanotify (7)).
 .TP
+.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
+.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
+Enable generation of audit log records about access mediation performed by
+permission events. The permission event response has to be marked with
+.B FAN_AUDIT
+flag for audit log record to be generated.
+.TP
 .BR FAN_REPORT_FID " (since Linux 5.1)"
 .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
 This value allows the receipt of events which contain additional information
diff --git a/man7/fanotify.7 b/man7/fanotify.7
index 5804a1f30d6c..b5f096304cf4 100644
--- a/man7/fanotify.7
+++ b/man7/fanotify.7
@@ -588,7 +588,14 @@ to deny the file operation.
 .PP
 If access is denied, the requesting application call will receive an
 .BR EPERM
-error.
+error. Additionally, if the notification group has been created with
+.B FAN_ENABLE_AUDIT
+flag,
+.B FAN_AUDIT
+flag can be set in the
+.I response
+field. In that case audit subsystem will log information about the access
+decision to the audit logs.
 .\"
 .SS Closing the fanotify file descriptor
 When all file descriptors referring to the fanotify notification group are
-- 
2.16.4

Re: [PATCH] fanotify: Document FAN_AUDIT flag

[Alejandro Colomar (man-pages)]

Hi Jan,

Please break lines at significant points,
instead of just when it wraps at the right margin;
as I did in this little paragraph.

See man-pages(7)::STYLE GUIDE::Use semantic newlines

Thanks,

Alex

On 12/2/20 4:43 PM, Jan Kara wrote:
> Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.
> 
> Signed-off-by: Jan Kara <jack@suse.cz>
> ---
>  man2/fanotify_init.2 | 7 +++++++
>  man7/fanotify.7      | 9 ++++++++-
>  2 files changed, 15 insertions(+), 1 deletion(-)
> 
> OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
> Steve glanced over it from the audit side to check things are sane.
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index ca03b11dc98a..6becc7a680db 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -155,6 +155,13 @@ supplied to
>  (see
>  .BR fanotify (7)).
>  .TP
> +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
> +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
> +Enable generation of audit log records about access mediation performed by
> +permission events. The permission event response has to be marked with
> +.B FAN_AUDIT
> +flag for audit log record to be generated.
> +.TP
>  .BR FAN_REPORT_FID " (since Linux 5.1)"
>  .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
>  This value allows the receipt of events which contain additional information
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 5804a1f30d6c..b5f096304cf4 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -588,7 +588,14 @@ to deny the file operation.
>  .PP
>  If access is denied, the requesting application call will receive an
>  .BR EPERM
> -error.
> +error. Additionally, if the notification group has been created with
> +.B FAN_ENABLE_AUDIT
> +flag,
> +.B FAN_AUDIT
> +flag can be set in the
> +.I response
> +field. In that case audit subsystem will log information about the access
> +decision to the audit logs.
>  .\"
>  .SS Closing the fanotify file descriptor
>  When all file descriptors referring to the fanotify notification group are
> 

Re: [PATCH] fanotify: Document FAN_AUDIT flag

[Jan Kara]

Hi!

On Wed 02-12-20 16:57:23, Alejandro Colomar (man-pages) wrote:
> Please break lines at significant points,
> instead of just when it wraps at the right margin;
> as I did in this little paragraph.
> 
> See man-pages(7)::STYLE GUIDE::Use semantic newlines

OK, I'll do that for the submission of the next patch version.

								Honza

> On 12/2/20 4:43 PM, Jan Kara wrote:
> > Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.
> > 
> > Signed-off-by: Jan Kara <jack@suse.cz>
> > ---
> >  man2/fanotify_init.2 | 7 +++++++
> >  man7/fanotify.7      | 9 ++++++++-
> >  2 files changed, 15 insertions(+), 1 deletion(-)
> > 
> > OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
> > Steve glanced over it from the audit side to check things are sane.
> > 
> > diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> > index ca03b11dc98a..6becc7a680db 100644
> > --- a/man2/fanotify_init.2
> > +++ b/man2/fanotify_init.2
> > @@ -155,6 +155,13 @@ supplied to
> >  (see
> >  .BR fanotify (7)).
> >  .TP
> > +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
> > +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
> > +Enable generation of audit log records about access mediation performed by
> > +permission events. The permission event response has to be marked with
> > +.B FAN_AUDIT
> > +flag for audit log record to be generated.
> > +.TP
> >  .BR FAN_REPORT_FID " (since Linux 5.1)"
> >  .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
> >  This value allows the receipt of events which contain additional information
> > diff --git a/man7/fanotify.7 b/man7/fanotify.7
> > index 5804a1f30d6c..b5f096304cf4 100644
> > --- a/man7/fanotify.7
> > +++ b/man7/fanotify.7
> > @@ -588,7 +588,14 @@ to deny the file operation.
> >  .PP
> >  If access is denied, the requesting application call will receive an
> >  .BR EPERM
> > -error.
> > +error. Additionally, if the notification group has been created with
> > +.B FAN_ENABLE_AUDIT
> > +flag,
> > +.B FAN_AUDIT
> > +flag can be set in the
> > +.I response
> > +field. In that case audit subsystem will log information about the access
> > +decision to the audit logs.
> >  .\"
> >  .SS Closing the fanotify file descriptor
> >  When all file descriptors referring to the fanotify notification group are
> > 
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

Ping: [PATCH] fanotify: Document FAN_AUDIT flag

[Alejandro Colomar (man-pages)]

Hi Honza,

Linux 5.10 has been recently released.
Do you have any updates for this patch?

Thanks,

Alex

On 12/2/20 5:19 PM, Jan Kara wrote:
> Hi!
> 
> On Wed 02-12-20 16:57:23, Alejandro Colomar (man-pages) wrote:
>> Please break lines at significant points,
>> instead of just when it wraps at the right margin;
>> as I did in this little paragraph.
>>
>> See man-pages(7)::STYLE GUIDE::Use semantic newlines
> 
> OK, I'll do that for the submission of the next patch version.
> 
> 								Honza
> 
>> On 12/2/20 4:43 PM, Jan Kara wrote:
>>> Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.
>>>
>>> Signed-off-by: Jan Kara <jack@suse.cz>
>>> ---
>>>  man2/fanotify_init.2 | 7 +++++++
>>>  man7/fanotify.7      | 9 ++++++++-
>>>  2 files changed, 15 insertions(+), 1 deletion(-)
>>>
>>> OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
>>> Steve glanced over it from the audit side to check things are sane.
>>>
>>> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
>>> index ca03b11dc98a..6becc7a680db 100644
>>> --- a/man2/fanotify_init.2
>>> +++ b/man2/fanotify_init.2
>>> @@ -155,6 +155,13 @@ supplied to
>>>  (see
>>>  .BR fanotify (7)).
>>>  .TP
>>> +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
>>> +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
>>> +Enable generation of audit log records about access mediation performed by
>>> +permission events. The permission event response has to be marked with
>>> +.B FAN_AUDIT
>>> +flag for audit log record to be generated.
>>> +.TP
>>>  .BR FAN_REPORT_FID " (since Linux 5.1)"
>>>  .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
>>>  This value allows the receipt of events which contain additional information
>>> diff --git a/man7/fanotify.7 b/man7/fanotify.7
>>> index 5804a1f30d6c..b5f096304cf4 100644
>>> --- a/man7/fanotify.7
>>> +++ b/man7/fanotify.7
>>> @@ -588,7 +588,14 @@ to deny the file operation.
>>>  .PP
>>>  If access is denied, the requesting application call will receive an
>>>  .BR EPERM
>>> -error.
>>> +error. Additionally, if the notification group has been created with
>>> +.B FAN_ENABLE_AUDIT
>>> +flag,
>>> +.B FAN_AUDIT
>>> +flag can be set in the
>>> +.I response
>>> +field. In that case audit subsystem will log information about the access
>>> +decision to the audit logs.
>>>  .\"
>>>  .SS Closing the fanotify file descriptor
>>>  When all file descriptors referring to the fanotify notification group are
>>>

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] fanotify: Document FAN_AUDIT flag

[Steve Grubb]

On Wednesday, December 2, 2020 10:43:54 AM EST Jan Kara wrote:
> Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.
> 
> Signed-off-by: Jan Kara <jack@suse.cz>

Looks good. Sorry about the delay.

Acked-by: Steve Grubb <sgrubb@redhat.com>

> ---
>  man2/fanotify_init.2 | 7 +++++++
>  man7/fanotify.7      | 9 ++++++++-
>  2 files changed, 15 insertions(+), 1 deletion(-)
> 
> OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
> Steve glanced over it from the audit side to check things are sane.
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index ca03b11dc98a..6becc7a680db 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -155,6 +155,13 @@ supplied to
>  (see
>  .BR fanotify (7)).
>  .TP
> +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
> +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
> +Enable generation of audit log records about access mediation performed by
> +permission events. The permission event response has to be marked with
> +.B FAN_AUDIT
> +flag for audit log record to be generated.
> +.TP
>  .BR FAN_REPORT_FID " (since Linux 5.1)"
>  .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
>  This value allows the receipt of events which contain additional
> information diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 5804a1f30d6c..b5f096304cf4 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -588,7 +588,14 @@ to deny the file operation.
>  .PP
>  If access is denied, the requesting application call will receive an
>  .BR EPERM
> -error.
> +error. Additionally, if the notification group has been created with
> +.B FAN_ENABLE_AUDIT
> +flag,
> +.B FAN_AUDIT
> +flag can be set in the
> +.I response
> +field. In that case audit subsystem will log information about the access
> +decision to the audit logs.
>  .\"
>  .SS Closing the fanotify file descriptor
>  When all file descriptors referring to the fanotify notification group are

Re: [PATCH] fanotify: Document FAN_AUDIT flag

[Michael Kerrisk (man-pages)]

On 12/2/20 4:43 PM, Jan Kara wrote:
> Document FAN_AUDIT and related FAN_ENABLE_AUDIT flags.
> 
> Signed-off-by: Jan Kara <jack@suse.cz>

Thanks, Jan. Applied with Steve's Acked-by

Cheers,

Michael

> ---
>  man2/fanotify_init.2 | 7 +++++++
>  man7/fanotify.7      | 9 ++++++++-
>  2 files changed, 15 insertions(+), 1 deletion(-)
> 
> OK, here's my attempt to document the FAN_AUDIT flag. It would be nice if
> Steve glanced over it from the audit side to check things are sane.
> 
> diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2
> index ca03b11dc98a..6becc7a680db 100644
> --- a/man2/fanotify_init.2
> +++ b/man2/fanotify_init.2
> @@ -155,6 +155,13 @@ supplied to
>  (see
>  .BR fanotify (7)).
>  .TP
> +.BR FAN_ENABLE_AUDIT " (since Linux 4.15)"
> +.\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269
> +Enable generation of audit log records about access mediation performed by
> +permission events. The permission event response has to be marked with
> +.B FAN_AUDIT
> +flag for audit log record to be generated.
> +.TP
>  .BR FAN_REPORT_FID " (since Linux 5.1)"
>  .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360
>  This value allows the receipt of events which contain additional information
> diff --git a/man7/fanotify.7 b/man7/fanotify.7
> index 5804a1f30d6c..b5f096304cf4 100644
> --- a/man7/fanotify.7
> +++ b/man7/fanotify.7
> @@ -588,7 +588,14 @@ to deny the file operation.
>  .PP
>  If access is denied, the requesting application call will receive an
>  .BR EPERM
> -error.
> +error. Additionally, if the notification group has been created with
> +.B FAN_ENABLE_AUDIT
> +flag,
> +.B FAN_AUDIT
> +flag can be set in the
> +.I response
> +field. In that case audit subsystem will log information about the access
> +decision to the audit logs.
>  .\"
>  .SS Closing the fanotify file descriptor
>  When all file descriptors referring to the fanotify notification group are
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/