7 files changed, 45 insertions, 4 deletions

diff --git a/src/man/firecfg.txt b/src/man/firecfg.txt
index 280a4aff1..42add6a41 100644
--- a/src/man/firecfg.txt
+++ b/src/man/firecfg.txt
@@ -146,3 +146,4 @@ Homepage: https://firejail.wordpress.com
 .BR firejail-login (5),
 .BR firejail-users (5),
 .BR jailcheck (1)
+.\" vim: set filetype=groff :
diff --git a/src/man/firejail-login.txt b/src/man/firejail-login.txt
index 05afd55b5..f03fc3c37 100644
--- a/src/man/firejail-login.txt
+++ b/src/man/firejail-login.txt
@@ -40,3 +40,4 @@ Homepage: https://firejail.wordpress.com
 .BR firejail-profile (5),
 .BR firejail-users (5),
 .BR jailcheck (1)
+.\" vim: set filetype=groff :
diff --git a/src/man/firejail-profile.txt b/src/man/firejail-profile.txt
index be1f55f0f..138aae8af 100644
--- a/src/man/firejail-profile.txt
+++ b/src/man/firejail-profile.txt
@@ -478,7 +478,11 @@ Allow tools such as strace and gdb inside the sandbox by whitelisting system cal
 #ifdef HAVE_APPARMOR
 .TP
 \fBapparmor
-Enable AppArmor confinement.
+Enable AppArmor confinement with the "firejail-default" AppArmor profile.
+.TP
+\fBapparmor profile_name
+Enable AppArmor confinement with a custom AppArmor profile.
+Note that the profile in question must already be loaded into the kernel.
 #endif
 .TP
 \fBcaps
@@ -1031,3 +1035,4 @@ Homepage: https://firejail.wordpress.com
 
 .UR https://github.com/netblue30/firejail/wiki/Creating-Profiles
 .UE
+.\" vim: set filetype=groff :
diff --git a/src/man/firejail-users.txt b/src/man/firejail-users.txt
index e3cce7ed5..7aa151680 100644
--- a/src/man/firejail-users.txt
+++ b/src/man/firejail-users.txt
@@ -60,3 +60,4 @@ Homepage: https://firejail.wordpress.com
 .BR firejail-profile (5),
 .BR firejail-login (5),
 .BR jailcheck (1)
+.\" vim: set filetype=groff :
diff --git a/src/man/firejail.txt b/src/man/firejail.txt
index 087d1c85a..1dd5508b3 100644
--- a/src/man/firejail.txt
+++ b/src/man/firejail.txt
@@ -67,6 +67,17 @@ Firejail allows the user to manage application security using security profiles.
 Each profile defines a set of permissions for a specific application or group
 of applications. The software includes security profiles for a number of more common
 Linux programs, such as Mozilla Firefox, Chromium, VLC, Transmission etc.
+.\" TODO: Explain the security/usability tradeoffs from #4601.
+.PP
+Firejail is currently implemented as an SUID binary, which means that if a
+malicious or compromised user account manages to exploit a bug in Firejail,
+that could ultimately lead to a privilege escalation to root.
+To mitigate this, it is recommended to only allow trusted users to run firejail
+(see firejail-users(5) for details on how to achieve that).
+For more details on the security/usability tradeoffs of Firejail, see:
+.UR https://github.com/netblue30/firejail/discussions/4601
+#4601
+.UE
 .PP
 Alternative sandbox technologies like snap (https://snapcraft.io/) and flatpak (https://flatpak.org/)
 are not supported. Snap and flatpak packages have their own native management tools and will
@@ -122,7 +133,13 @@ $ firejail --allusers
 #ifdef HAVE_APPARMOR
 .TP
 \fB\-\-apparmor
-Enable AppArmor confinement. For more information, please see \fBAPPARMOR\fR section below.
+Enable AppArmor confinement with the "firejail-default" AppArmor profile.
+For more information, please see \fBAPPARMOR\fR section below.
+.TP
+\fB\-\-apparmor=profile_name
+Enable AppArmor confinement with a custom AppArmor profile.
+Note that profile in question must already be loaded into the kernel.
+For more information, please see \fBAPPARMOR\fR section below.
 .TP
 \fB\-\-apparmor.print=name|pid
 Print the AppArmor confinement status for the sandbox identified by name or by PID.
@@ -174,6 +191,13 @@ Blacklist directory or file. File globbing is supported, see \fBFILE GLOBBING\fR
 .br
 
 .br
+Symbolic link handling: Blacklisting a path that is a symbolic link will also
+blacklist the path that it points to.
+For example, if ~/foo is blacklisted and it points to /foo, then /foo will also
+be blacklisted.
+.br
+
+.br
 Example:
 .br
 $ firejail \-\-blacklist=/sbin \-\-blacklist=/usr/sbin
@@ -2905,8 +2929,14 @@ all directories in /usr.
 .br
 
 .br
-Symbolic link handling: with the exception of user home, both the link and the real file should be in
-the same top directory. For user home, both the link and the real file should be owned by the user.
+Symbolic link handling: Whitelisting a path that is a symbolic link will also
+whitelist the path that it points to.
+For example, if ~/foo is whitelisted and it points to ~/bar, then ~/bar will
+also be whitelisted.
+Restrictions: With the exception of the user home directory, both the link and
+the real file should be in the same top directory.
+For symbolic links in the user home directory, both the link and the real file
+should be owned by the user.
 .br
 
 .br
@@ -3611,3 +3641,4 @@ Homepage: https://firejail.wordpress.com
 .UE ,
 .UR https://github.com/netblue30/firejail
 .UE
+.\" vim: set filetype=groff :
diff --git a/src/man/firemon.txt b/src/man/firemon.txt
index fd58a7168..9d0785a4a 100644
--- a/src/man/firemon.txt
+++ b/src/man/firemon.txt
@@ -118,3 +118,4 @@ Homepage: https://firejail.wordpress.com
 .BR firejail-login (5),
 .BR firejail-users (5),
 .BR jailcheck (1)
+.\" vim: set filetype=groff :
diff --git a/src/man/jailcheck.txt b/src/man/jailcheck.txt
index 483f47fb9..e889ea91b 100644
--- a/src/man/jailcheck.txt
+++ b/src/man/jailcheck.txt
@@ -115,3 +115,4 @@ Homepage: https://firejail.wordpress.com
 .BR firejail-profile (5),
 .BR firejail-login (5),
 .BR firejail-users (5),
+.\" vim: set filetype=groff :