shell: Expand documentation in firejail.profile

Explain what content should go in the profile and what the two inclusions
are for.

Bug: T257207
Change-Id: I7a0fbc558a85baa91624414f67f84d2dc23a41bb

diff --git a/includes/shell/firejail.profile b/includes/shell/firejail.profile
index 07f059b..d87d3ee 100644 (file)
--- a/includes/shell/firejail.profile
+++ b/includes/shell/firejail.profile
@@ -1,7 +1,16 @@
 # Firejail profile used by MediaWiki when shelling out
+# Most rules are applied via command-line flags controlled by the
+# Shell::RESTRICTION_* constants.
+# Rules added to this file must be compatible with every command that could
+# be invoked. If something might need to be disabled, then it should be added
+# as a Shell:RESTRICTION_* constant instead so that commands can opt-in/out.
+
 # See <https://firejail.wordpress.com/features-3/man-firejail-profile/> for
-# syntax documentation
-# Persistent local customizations
+# syntax documentation.
+
+# Optionally allow sysadmins to set extra restrictions that apply to their
+# MediaWiki setup, e.g. disallowing access to extra private directories.
 include /etc/firejail/mediawiki.local
-# Persistent global definitions
+
+# Include any global firejail customizations.
 include /etc/firejail/globals.local