Creating Profiles

• General
• Profiles
  • Locations and Types
    • File locations
  • Steps for contributing your own profile
• Common mistakes

~/.config/firejail/ is the place for user-defined profiles.

The default configuration starts any program with a profile in a sandbox. However a user can still run without firejail (/usr/bin/firefox) and use the commandline (firejail --noprofile firefox, firejail --profile=myprofile firefox). Likewise any local non-admin user may change firejail behavior by editing ~/.config/firejail.

Profiles are configurations defined as how Firejail will treat the application being run under it. This defines options such as what directories it has access to, what base system functionality it has access to, and so on.

The execution sequence is generally the following:

1. Command line parameter execution as customizations
2. Recursive running the profiles
   1. Redirection due to alias profile (loading full profile)
   2. Local customization
   3. Global customization
   4. Profile content (which often uses common settings)

See Locations and Types, or the profile template in /usr/share/doc/firejail/profile.template and the man page for understanding the customizations.

Every file in a firejail directory (/etc/firejail or /usr/local/etc/firejail when compiled without --prefix=/usr, ~/.config/firejail) is basically a profile. They all follow the same syntax. However, there are still some different file types:

• Regular profiles (.profile)
  • It contains settings for a specific application, like curl.profile
  • There are a few subtypes:
    • Regular profiles, like curl.profile
    • Alias profiles, like atom-beta.profile. They usually only contain include statements. atom-beta is very similar to atom, so the same sandboxing settings are used.
    • Common profiles, like firefox-common.profile. Some applications have different flavors, like Firefox, and all have some sandboxing settings in common.
• Overrides (.local)
  • This file contains overrides which can override specific parts of a regular profile, like curl.local. Also see this wiki page
  • globals.local is a special override file. It will affect every regular profile.
• Includes (.inc)
  • Every file type can be included, see the recurring include globals.local and include $application.local parts of almost every profile but this file type usually contains useful reusable statements, like disable-common.inc
  • An include will fail if the file you want to include does not exist, except when trying to include a .local file.
  • There are some subtypes:
    • Includes that start with allow handle allowing access to certain paths. e.g allow-ruby.inc will allow access to certain ruby paths, which the application may need for addons/plugins.
    • disable-* includes handle blacklisting paths, like disallowing access to sensible files.
    • whitelist-* includes contain statements necessary for whitelisting profiles
    • Everything else is a special application-specific include, like firefox-common-addons.inc

Depending on where you put a file, it might override other files. Files in ~/.config/firejail have a higher priority than /etc/firejail (or /usr/local/etc/firejail), so if /etc/firejail/curl.profile and ~/.config/firejail/curl.profile both exist, firejail uses ~/.config/firejail/curl.profile. This applies to every file type mentioned above.

System-wide profiles for pull requests are supposed to be created in folder etc and are based on a template in /usr/share/doc/firejail/profile.template.

The process is fairly straightforward, given the template:

1. Copy etc/templates/profile.template to ~/PROGRAM.profile
2. Open ~/PROGRAM.profile in a text editor and follow the introductions in the file. To run use firejail --profile=PROGRAM.profile PROGRAM. If your program acts like a similar program (e.g. an electron app is similar to Discord and teams-for-linux), you can look at their profiles.
   The debugger options --debug, --debug-{blacklists, caps, errnos, private-lib, protocols, syscalls, whitelists}, --trace, --build and --audit may be of use.
3. Create a pull request.

1. blacklist PATH: PATH is still present, but not accessible (with whitelist they don't exist)
2. noblacklist ~/Documents/presentations blacklist ~/Documents: does not work
3. whitelisting in profiles: new files are not saved (=> don't use for text editors, image editing software, ... )
4. Write fail-safe profiles: If someone decides to un-whitelist the wire profile, sensitive files should not be be visible inside the sandbox. For example for the wire profile, see whitelist-noblacklist

noblacklist ${HOME}/.config/Wire
mkdir ${HOME}/.config/Wire
whitelist ${HOME}/.config/Wire