Creating Profiles

• General
• Profiles
  • Locations and Types
  • Difference of local vs global and full vs adaption profiles
  • Steps for contributing your own profile
• Common mistakes

General

~/.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=myprofiel firefox). Likewise any local non-admin user may change firejail behavior by editing ~/.config/firejail.

Profiles

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.

Locations and Types

Upon execution Firejail first looks in ~/.config/firejail/ for a profile and if it doesn't find one, it looks in /etc/firejail (If firejail is self-compiled without --prefix=/usr, profiles are located under /usr/local/etc/firejail). There are four types of profiles:

1. Full profiles (PROGRAM_NAME.profile)
   contain a whole profile
   like etc/thunderbird.profile.
2. Alias profiles (PROGRAM_NAME.profile)
   refer to another profile
   ie in etc/thunderbird-beta.profile using include thunderbird.profile.
3. Program specific profiles (PROGRAM_NAME.local)
   add commands to an existing full profile like for allowing local features
   ie in a self-created file thunderbird.local with content ignore nodbus.
4. The global profile (globals.local)
   adds the commands to all existing full profiles
   by creating such profile.

Therefore the easiest way to add one or more commands to a profile, is to create a .local file in ~/.config/firejail/ and write the new commands to it.
noblacklist/nowhitelist permits/forbids file/location in any later blacklist/whitelist. blacklist/whitelist permits/forbids everything not explicitly forbidden/permitted.
Flexible adaptions belong into scripts/shell commands like firejail --whitelist=~/Downloads/thunderbird thunderbird for optionally allowance of appending data.

Difference of local vs global and full vs adaption profiles

For each including of files, the local profiles in ~/.config/firejail have precedence before global profiles in etc.
For local and global profiles full profiles <PROGRAM>.profile and local adaptions <PROGRAM>.local are loaded with according precedence.
For example, we can write a profile thunderbird.profile inside ~/.config/firejail to be loaded instead of the profile in etc or we can write local adaptions inside ~/.config/firejail for local adaptions as thunderbird.local.

Steps for contributing your own profile

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.

Common mistakes

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