Merge pull request #6622 from powerjungle/chore/fix-whitelist-man

docs: improve whitelist and blacklist descriptions in man pages

Author: netblue30

src/man/firejail-profile.5.in

@@ -248,7 +248,21 @@ for more details.
 Examples:
 .TP
 \fBblacklist file_or_directory
-Blacklist directory or file. Examples:
+Blacklist directory or file. This makes a file or directory
+completely inaccessible. All other files and directories are unaffected.
+The blacklisted file or directory is still visible on the filesystem,
+even if it's inaccessible.
+.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 /bar, then /bar will also
+be blacklisted.
+.br
+
+.br
+Examples:
 .br
 
 .br
@@ -452,16 +466,36 @@ Mount an empty tmpfs filesystem on top of directory. Directories outside user ho
 Blacklist violations logged to syslog.
 .TP
 \fBwhitelist file_or_directory
-Whitelist directory or file. A temporary file system is mounted on the top directory, and the
-whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent,
-everything else is discarded when the sandbox is closed. The top directory can be
-all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and
-all directories in /usr.
+Whitelist directory or file. A temporary file system is mounted on the top directory.
+In the context of firejail, top directory means, if the whitelisted file's path is
+for example /etc/somedir/somefile, then the top directory would be /etc.
+All other top directories like /opt, /usr and so on, haven't changed, so all files there
+are still accessible, unless a file or directory inside them is also whitelisted.
+This is why sometimes it's beneficial to use blacklist in combination with whitelist,
+if used for different top directories.
 .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.
+The whitelisted files are mount-binded inside. Modifications to whitelisted files are
+persistent, everything else in the same top directory is discarded when the sandbox is closed.
+.br
+
+.br
+The top directory can be most directories in /, but there are some special cases.
+The /proc and /sys top directories aren't allowed, but /sys/module is allowed.
+Also /run/user/$UID, $HOME and all directories in /usr are treated as a top directory.
+.br
+
+.br
+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.
+.br
+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.
 
 .TP
 \fBwhitelist-ro file_or_directory

src/man/firejail.1.in

@@ -190,7 +190,10 @@ Example:
 # firejail \-\-bind=/config/etc/passwd,/etc/passwd
 .TP
 \fB\-\-blacklist=dirname_or_filename
-Blacklist directory or file. File globbing is supported, see \fBFILE GLOBBING\fR section for more details.
+Blacklist directory or file. This makes a file or directory
+completely inaccessible. All other files and directories are unaffected.
+The blacklisted file or directory is still visible on the filesystem,
+even if it's inaccessible.
 .br
 
 .br
@@ -200,6 +203,10 @@ For example, if ~/foo is blacklisted and it points to /bar, then /bar will also
 be blacklisted.
 .br
 
+.br
+File globbing is supported, see \fBFILE GLOBBING\fR section for more details.
+.br
+
 .br
 Example:
 .br
@@ -3116,18 +3123,32 @@ $ firejail \-\-net=br0 --veth-name=if0
 #endif
 .TP
 \fB\-\-whitelist=dirname_or_filename
-Whitelist directory or file. A temporary file system is mounted on the top directory, and the
-whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent,
-everything else is discarded when the sandbox is closed. The top directory can be
-all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and
-all directories in /usr.
+Whitelist directory or file. A temporary file system is mounted on the top directory.
+In the context of firejail, top directory means, if the whitelisted file's path is
+for example /etc/somedir/somefile, then the top directory would be /etc.
+All other top directories like /opt, /usr and so on, haven't changed, so all files there
+are still accessible, unless a file or directory inside them is also whitelisted.
+This is why sometimes it's beneficial to use blacklist in combination with whitelist,
+if used for different top directories.
+.br
+
+.br
+The whitelisted files are mount-binded inside. Modifications to whitelisted files are
+persistent, everything else in the same top directory is discarded when the sandbox is closed.
+.br
+
+.br
+The top directory can be most directories in /, but there are some special cases.
+The /proc and /sys top directories aren't allowed, but /sys/module is allowed.
+Also /run/user/$UID, $HOME and all directories in /usr are treated as a top directory.
 .br
 
 .br
 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.
+.br
 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