Creating Profiles

Profile Description

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.

Profile Locations/Types

Firejail's installation path depends on the package or install configuration being usually /usr/local or /.
Upon execution Firejail first looks in ~/.config/firejail/ for a profile and if it doesn't find one, it looks in /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.

TODO: write tests for overwrite handling of folders(noblacklist vs nowhitelist vs blacklist-nolog vs blacklist vs whitelist vs read-only).
noblacklist permits file/location in any later blacklist, whereas nowhitelist forbids file/location in any later blacklist. blacklist permits everything not explicitly forbidden, whereas whitelist forbids everything not explicitly permitted. read-only usually involved often used program paths like /bin.

For further flexibility we can use shell commands like firejail --whitelist=~/Downloads/thunderbird thunderbird.

System Profile Definition

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.

Contribution steps for defining your own profile

The process is fairly straightforward, given the template:

1. Create a fork of the project to your own instance
2. Check out that fork you created.
3. Create a branch, ideally with a descriptive name
4. Copy etc/templates/profile.template into etc/PROGRAM.template

At this point, you can either create a symlink from your /etc/firejail/PROGRAM.template to your copy in the repository, or you can copy your template after edits.

5. Create a symlink from /usr/local/bin/<PROGRAM> to /usr/bin/firejail

At this point, the profile is in the most restrictive mode possible, and running the program may not launch or give errors. You can comment out lines with a # symbol, rerun, and rinse and repeat til you get a working solution.
Alternatively, 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 to get started on your own.
The debugger options --alow-debuggers, --debug, --debug{-blacklists,-caps,-errnos,-private-lib,-protocols,-syscalls,-whitelists} may be of use.

6. Audit your profile by calling firejail --audit <PROGRAM> on the according profile.

7. Push your changes to your repository and create a pull request.