# This publication is intellectual property of Canonical Ltd. Its contents
# can be duplicated, either in part or in whole, provided that a copyright
# label is visibly located on each copy.
#
# All information found in this book has been compiled with utmost
# attention to detail. However, this does not guarantee complete accuracy.
# Neither Canonical Ltd, the authors, nor the translators shall be held
# liable for possible errors or the consequences thereof.
#
# Many of the software and hardware descriptions cited in this book
# are registered trademarks. All trade names are subject to copyright
# restrictions and may be registered trade marks. Canonical Ltd
# essentially adheres to the manufacturer's spelling.
#
# Names of products and trademarks appearing in this book (with or without
# specific notation) are likewise subject to trademark and trade protection
# laws and may thus fall under copyright restrictions.
#


=pod

=head1 NAME

aa-notify - display information about logged AppArmor messages.

=head1 SYNOPSIS

B<aa-notify> [option]

=head1 DESCRIPTION

B<aa-notify> will display a summary or provide desktop notifications
for AppArmor DENIED messages.

=head1 OPTIONS

B<aa-notify> accepts the following arguments:

=over 4

=item -p, --poll

poll AppArmor logs and display desktop notifications. Can be used with '-s'
option to display a summary on startup.

=item --display $DISPLAY

set the DISPLAY environment variable to $DISPLAY
(might be needed if sudo resets $DISPLAY)

=item --xauthority XAUTHORITY

set the XAUTHORITY environment variable (might be needed if sudo
resets XAUTHORITY)

=item -f FILE, --file=FILE

search FILE for AppArmor messages

=item -l, --since-last

show summary since last login.

=item -s NUM, --since-days=NUM

show summary for last NUM of days.

=item -u USER, --user=USER

user to drop privileges to when running privileged. When used with the -p
option, this should be set to the user that will receive desktop notifications.
This has no effect when running under sudo.

=item -w NUM, --wait=NUM

wait NUM seconds before displaying notifications (for use with -p)

=item -m, --merge-notifications

Merge notification for improved readability (with -p)

=item -F, --foreground

Do not fork to the background

=item --prompt-filter operation

Which operations should use a popup prompt window instead of a system
notification.

eg.
  --prompt-filter="userns"

=item --filter.TYPE FILTER

Apply filters as to select which apparmor messages should be allowed
through based on which messages match the filter parameters (see also
custom notification filtering in CONFIGURATION). Filters use Python's
regular expression syntax.

Supported Filter TYPE:

=over 4

=item profile   - name of the profile
=item mode      - mode eg, DENIED, ALLOWED, STATUS
-item operation - operation being mediated eg. open
-item name      - name of object, eg. file name /home/foo/bar
-item denied    - permissions that were denied
-item family    - socket family, eg. inet, inet6, netlink
-item socket    - socket type. eg. stream, dgram, rdm

=back

=item -L, --local [{yes,no,auto}]

add rules to a local profiles instead of the real profiles.
This simplify profiles' deployment by keeping local modifications self-contained.
 - B<yes>: always use a local profile
 - B<no>: never use a local profile
 - B<auto>: use a local profile if the main profile already relies on a local profile

=item -v, --verbose

show messages with summaries.

=item debug

provide debug output

=item -h, --help

displays a short usage statement.

=back

=head1 CONFIGURATION

System-wide configuration for B<aa-notify> is done via
/etc/apparmor/notify.conf:

  # Set to 'no' to disable AppArmor notifications globally
  show_notifications="yes"

  # Special profiles used to remove privileges for unconfined binaries using user namespaces. Special profiles use Python's regular expression syntax. If unsure, leave as is.
  userns_special_profiles="unconfined,unprivileged_userns,unpriv_.*"

  # Theme for aa-notify GUI. See https://ttkthemes.readthedocs.io/en/latest/themes.html for available themes.
  interface_theme="ubuntu"

  # Binaries for which we ignore userns-related capability denials
  ignore_denied_capability="sudo,su"

  # Write change to local profiles if enabled to preserve regular profiles and simplify upgrades (yes, no, auto)
  use_local_profiles="yes"

  # OPTIONAL - kind of operations which display a popup prompt.
  prompt_filter="userns"

  # OPTIONAL - restrict using aa-notify to users in the given group
  # (if not set, everybody who has permissions to read the logfile can use it)
  # use_group="admin"

  # OPTIONAL - custom notification message body
  message_body="This is a custom notification message."

  # OPTIONAL - custom notification message footer
  message_footer="For more information visit https://foo.com"

  # OPTIONAL - custom notification filtering
  # Filters are used to reduce the output of information to only those entries that will match the filter. Filters use Python's regular expression syntax.
  filter.profile="^(foo|bar)$"	# Match the profile:		Only shows notifications for profiles "foo" or "bar"
  filter.mode="^STATUS$"	# Match the mode:		Only show notifications for "STATUS" messages, where mode can be:
	UNKNOWN		an unknown AppArmor mode
	ERROR		an error other than a regular denial occurred
	ALLOWED		a permissions request which did not match a rule, was allowed due to complain mode.
	DENIED		a permissions request was denied
	HINT		additional context information
	STATUS		some policy or enforcement change has occurred
	KILLED		a permission request was denied and the process that attempted the access was killed.
  filter.operation="^open$"	# Match the operation:		Only shows notifications for "open" operation
  filter.name="^(?!/usr/lib/)"	# Match the name:		Excludes notifications for names starting by "/usr/lib/"
  filter.denied="^r$"		# Match the denied_mask:	Only shows notifications where "r", and only "r", was denied
  filter.family="^inet$"	# Match the network family:	Only shows notifications for "inet" family
  filter.socket="stream"	# Match the network socket type: Only shows notifications for "stream" sockets

Per-user configuration is done via $XDG_CONFIG_HOME/apparmor/notify.conf (or
the deprecated ~/.apparmor/notify.conf if it exists):

  # set to 'yes' to enable AppArmor DENIED notifications
  show_notifications="yes"

=head1 BUGS

B<aa-notify> needs to be able to read the logfiles containing the
AppArmor DENIED messages.

If you find any additional bugs, please report them to Gitlab at
L<https://gitlab.com/apparmor/apparmor/-/issues>.

=head1 SEE ALSO

apparmor(7)

=cut
