1 files changed, 110 insertions, 18 deletions

diff --git a/etc/templates/profile.template b/etc/templates/profile.template
index d7da0ed20..892fd71ef 100644
--- a/etc/templates/profile.template
+++ b/etc/templates/profile.template
@@ -1,25 +1,91 @@
 # Firejail profile for PROGRAM_NAME
 # Description: DESCRIPTION
 # This file is overwritten after every install/update
+# --- CUT HERE ---
+# This is a generic template to help you with creation of profiles
+# for new programs. PRs welcome at https://github.com/netblue30/firejail/
+#
+# Rules to follow:
+#  - lines with one # are often used in profiles
+#  - lines with two ## are only needed in special situations
+#  - make the profile as restrictive as possible while still keeping the program useful
+#    (e. g. a program that is unable to save user's work is considered a bad practice)
+#  - dedicate some time (based on how complex the application is) to profile testing before raising
+#    a pull request
+#  - keep the sections structure, use a single empty line as a separator
+#  - entries within sections are alphabetically sorted
+#  - consider putting binary into src/firecfg/firecfg.config (keep list sorted) but beware
+#    to not do this for essential utilities as this may *break* your OS! (related discussion:
+#    https://github.com/netblue30/firejail/issues/2507)
+#  - remove this comment section and any generic comment past 'Persistent global definitions'
+#
+# Sections structure
+#   HEADER
+#   COMMENTS
+#   IGNORES
+#   NOBLACKLISTS
+#   ALLOW INCLUDES
+#   BLACKLISTS
+#   DISABLE INCLUDES
+#   MKDIRS
+#   WHITELISTS
+#   WHITELIST INCLUDES
+#   OPTIONS (caps*, net*, no*, protocol, seccomp*, shell none, tracelog)
+#   PRIVATE OPTIONS (disable-mnt, private-*, writable-*)
+#   SPECIAL OPTIONS (mdwx, noexec, read-only, join-or-start)
+#   REDIRECT INCLUDES
+#
+# The following macros may be used in path names to substitute common locations:
+#  ${DESKTOP}
+#  ${DOCUMENTS}
+#  ${DOWNLOADS}
+#  ${HOME} (user's home)
+#  ${PATH} (contents of PATH envvar)
+#  ${MUSIC}
+#  ${VIDEOS}
+#
+# Check contents of ~/.config/user-dirs.dirs to see how they translate to actual paths.
+#
+# --- CUT HERE ---
 ##quiet
 # Persistent local customizations
-#include PROFILE.local
+include PROFILE.local
 # Persistent global definitions
-#include globals.local
+include globals.local
 
 ##ignore noexec ${HOME}
+##ignore noexec /tmp
 
 ##blacklist PATH
+# Disable X11 (CLI only), see also 'x11 none' below
+#blacklist /tmp/.X11-unix
 
+# It is common practice to add files/dirs containing program-specific configuration
+# (often ${HOME}/PROGRAMNAME or ${HOME}/.config/PROGRAMNAME) into disable-programs.inc
+# (keep list sorted) and then disable blacklisting below.
+# One way to retrieve the files a program uses is:
+#  - launch binary with --private naming a sandbox
+#      `firejail --name=test --ignore=private-bin [--profile=PROFILE] --private BINARY`
+#  - work with the program, do some configuration changes and save them, open new documents,
+#    install plugins if they exists, etc
+#  - join the sandbox with bash:
+#      `firejail --join=test bash`
+#  - look what has changed and use that information to populate blacklist and whitelist sections
+#      `ls -aR`
 #noblacklist PATH
 
 # Allow python (blacklisted by disable-interpreters.inc)
-#noblacklist ${PATH}/python2*
-#noblacklist ${PATH}/python3*
-#noblacklist /usr/lib/python2*
-#noblacklist /usr/lib/python3*
-#noblacklist /usr/local/lib/python2*
-#noblacklist /usr/local/lib/python3*
+#include allow-python2.inc
+#include allow-python3.inc
+
+# Allow perl (blacklisted by disable-interpreters.inc)
+#include allow-perl.inc
+
+# Allow java (blacklisted by disable-devel.inc)
+#include allow-java.inc
+
+# Allow lua (blacklisted by disable-interpreters.inc)
+#include allow-lua.inc
 
 #include disable-common.inc
 #include disable-devel.inc
@@ -29,16 +95,24 @@
 #include disable-programs.inc
 #include disable-xdg.inc
 
+# This section often mirrors noblacklist section above. The idea is
+# that if a user feels too restricted (he's unable to save files into
+# home directory for instance) he/she may disable whitelist (nowhitelist)
+# in PROFILE.local but still be protected by BLACKLISTS section
+# (further explanation at https://github.com/netblue30/firejail/issues/1569)
 #mkdir PATH
-#mkfile PATH
+##mkfile PATH
 #whitelist PATH
 #include whitelist-common.inc
 #include whitelist-var-common.inc
 
 #apparmor
 #caps.drop all
+##caps.keep CAPS
+##hostname NAME
 # CLI only
 ##ipc-namespace
+# breaks sound and sometime dbus related functions
 #machine-id
 # 'net none' or 'netfilter'
 #net none
@@ -53,30 +127,48 @@
 #notv
 #nou2f
 #novideo
-#protocol unix,inet,inet6,netlink
+# Remove every not needed protocol
+#  - unix is usually needed
+#  - inet,inet6 only if internet access is requiered (see 'net none'/'netfilter' above)
+#  - netlink is rarely needed
+#  - packet almost never
+#protocol unix,inet,inet6,netlink,packet
 #seccomp
-##seccomp.drop SYSCALLS
+##seccomp.drop SYSCALLS (see also syscalls.txt)
 #shell none
 #tracelog
+# Prefer 'x11 none' instead of 'blacklist /tmp/.X11-unix' if 'net none' is set
+##x11 none
 
 #disable-mnt
 ##private
+# It's common practice to refer to the python executable(s) in private-bin with `python*`, which covers both v2 and v3
 #private-bin PROGRAMS
 #private-cache
 #private-dev
 #private-etc FILES
-# private-etc templates (see also #1734)
-#  Internet: ca-certificates,crypto-policies,nsswitch.conf,pki,resolv.conf,ssl
-#  Sound: alsa,asound.conf,machine-id,openal,pulse
-#  GTK: dconf,fonts,gtk-2.0,gtk-3.0,pango,xdg
-#  KDE/QT: fonts,kde4rc,kde5rc,ld.so.cache,machine-id,Trolltech.conf,xdg
-#  GUIs: fonts
-#  Alternatives: alternatives
+# private-etc templates (see also #1734, #2093)
+#  Common: alternatives,ld.so.cache,ld.so.conf,ld.so.conf.d,ld.so.preload,locale,locale.alias,locale.conf,localtime,mime.types,xdg
+#    Extra: magic,magic.mgc,passwd,group
+#  Networking: ca-certificates,ssl,pki,crypto-policies,nsswitch.conf,resolv.conf,hosts,host.conf,hostname,protocols,services,rpc
+#    Extra: proxychains.conf,gai.conf
+#  Sound: alsa,asound.conf,pulse,machine-id
+#  GUI: fonts,pango,X11
+#  GTK: dconf,gconf,gtk-2.0,gtk-3.0
+#  Qt: Trolltech.conf
+#  KDE: kde4rc,kde5rc
+#  3D: drirc,glvnd,bumblebee,nvidia
+#  D-Bus: dbus-1,machine-id
 ##private-lib LIBS
 ##private-opt NAME
 #private-tmp
+##writable-etc
+##writable-run-user
+##writable-var
+##writable-var-log
 
 ##env VAR=VALUE
 #memory-deny-write-execute
+##noexec PATH
 ##read-only ${HOME}
 ##join-or-start NAME