Skip to content

Creating Profiles

Jump to bottom Edit New page
Kelvin M. Klann edited this page Jul 21, 2024 · 44 revisions

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 applications without firejail (/usr/bin/firefox) and use parameters to specify profiles (firejail --noprofile firefox or firejail --profile=myprofile firefox). Any local non-admin user can also load their own profiles by placing them in ~/.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
  3. Redirection due to alias profile (loading full profile)
  4. Local customization
  5. Global customization
  6. 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

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 sensitive files.
      • whitelist-* includes contain statements necessary for whitelisting profiles
      • Everything else is a special application-specific include, like firefox-common-addons.inc

File locations

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.

Steps for contributing your own profile

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

The process is fairly straightforward:

  1. Copy etc/templates/profile.template to ~/PROGRAM.profile
  2. Open ~/PROGRAM.profile in a text editor and follow the instructions 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.

  1. If the program has its own configuration files/directories, add them to etc/inc/disable-programs.inc
  2. Add the program to src/firecfg/firecfg.config
  3. Submit 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, ... )

Guidelines

  1. Write fail-safe profiles that use blacklist, noblacklist and whitelist. Recall that the whitelist directive blacklists everything else, so a user might want to temporarily disable it in a .local override, in order to give a program access to another directory. If there's no blacklist, then the program will have access to everything in the user's home directory. The blacklists provide a failsafe if whitelists are disables. Then you need noblacklists for specific directories to allow a program to access them despite the profile including other disable-* profiles that do blacklist many programs. For more details, see the Wire whitelist-noblacklist and why we have blacklist, noblacklist, and whitelist in the same profile.
noblacklist ${HOME}/.config/Wire
mkdir ${HOME}/.config/Wire
whitelist ${HOME}/.config/Wire
Add a custom footer
Clone this wiki locally