Firejail: Wiki: Creating Profiles

[rusty-snake]

Issue for discussions about https://github.com/netblue30/firejail/wiki/Creating-Profiles

[jose1711]

I'd welcome some tips such as using strace to trace syscalls or touched files/directories, auditing profiles or using jail_prober.py

[rusty-snake]

@jose1711 if you can, start writing. :wink:

EDIT: We can also add firejail --trace and firejail --debug
EDIT2: and firejail --debug-*

[jose1711]

i wish i had that knowledge..

[matu3ba]

find / -maxdepth 10 \( -type f -or -type d \) -name "$1" -print 2> /dev/null
returns /usr/local/
as folder where firejail is installed.
For older versions of firejail /etc/firejail/ however might be correct.
In /run/firejail/ temporary instance information are stored.
[Put this in the beginning or to Home]

Profile Locations/Types explains 3 types of profiles, but lists 4.
The difference of usage is not very clear there.

"system-wide profiles are organized in a consistent manner"
I do not get the purpose of that sentence. Remove and explain better when which profile is used.

Change "Process/Steps for defining your own template (Contribution)" to "Contribute a new profile" or explain the difference between template and profile.

[rusty-snake]

find / -maxdepth 10 ( -type f -or -type d ) -name "$1" -print 2> /dev/null
returns /usr/local/
as folder where firejail is installed.
For older versions of firejail /etc/firejail/ however might be correct.

@matu3ba if you compile firejail your self (without ./configure --prefix=/usr), firejail is installed under /usr/local, but if you add --prefix=/usr to configure or use a packet from a distro /etc/firejail is correct.

[rusty-snake]

done

explains 3 types of profiles, but lists 4.

Fixed.
@matu3ba you should can edit the wiki, fell free to directly improve the wiki.

EDIT:

The difference of usage is not very clear there.

Maybe we should a some examples.

Examples:
 1. [transmission-cli.profile](https://github.com/netblue30/firejail/blob/master/etc/transmission-cli.profile)
    Contains all options to make `transmission-cli` run secure but without trouble.
 2. [transmission-create.profile](https://github.com/netblue30/firejail/blob/master/etc/transmission-create.profile)
    `transmission-create` need the same options as `transmission-cli`, so `transmission-create.profile` just `include` `transmission-cli.profile`.
 3. `transmission-cli.local`
     Create by the user to (1) add something (e.g. `private-bin transmission-cli`) or (2) `ignore` something (e.g. `ignore private-etc`) to/in `transmission-cli.profile`.
 4. `globals.local`
    Create by the user to (1) add something (e.g. `net none`) or (2) `ignore` something (e.g. `ignore apparmor`) to/in all profiles.

[matu3ba]

@rusty-snake Please review my changes.
The language needs rephrasing though.
I did add some examples for my thunderbird adaption.
/usr/share/doc/firejail/profile.template does not exist on my system.
The noblacklist, whitelist behavior needs more explanation.

[rusty-snake]

done

@matu3ba looks great.

The language needs rephrasing though.

For me too :grinning: .

firejail/etc/templates/profile.template

May we should leave the firejail/

Your install path of firejail may change from /usr/local to / depending on your package or install configuration.
Firejail first looks in ~/.config/firejail/ for a profile and if it doesn't find one then it looks in /etc/firejail.
The execution order can be seen for the thunderbird profile as include thunderbird.local and then include globals.local.

Should be reworked again. Let's find a solution here.

/usr/share/doc/firejail/profile.template does not exist on my system.

You need FJ 0.9.61 (lastet git) ~or newer~.

The noblacklist, whitelist behavior needs more explanation.

The wiki is new, there's a whole lot more to do.

[matu3ba]

@rusty-snake
Did rework the whole thing. Please review.
For the test cases (I did not find any): Could you briefly tell, what is to be expected from conflicts?

[rusty-snake]

I think the focus of this site should be on profiles therefore nowhitelist, blacklist-nolog, read-only should be omitted.

nowhitelist forbids file/location in any later ~blacklist~ _whitelist_.

I rewrite the "Steps for contributing your own profile" section, fell free to suggest anything.

For the test cases (I did not find any): Could you briefly tell, what is to be expected from conflicts?

??

[matu3ba]

I think the focus of this site should be on profiles therefore nowhitelist, blacklist-nolog, read-only should be omitted.

nowhitelist forbids file/location in any later ~blacklist~ _whitelist_.

I rewrite the "Steps for contributing your own profile" section, fell free to suggest anything.

That looks very nice and comprehensive now, but I would like to mention --audit for checking big flaws or why was it written in the first place for not using it?

For the test cases (I did not find any): Could you briefly tell, what is to be expected from conflicts?

??

read-only had a bug you also commented in #1235 , which is why I wanted to explain and test this.

[rusty-snake]

That looks very nice and comprehensive now, but I would like to mention --audit for checking big flaws or why was it written in the first place for not using it?

if you reverberate to the template, everything that doesn't cause problems should be enabled, I think it might confuse rather. So I would suggest to add it to --debug, --tarce, ... and not as a single point.

read-only had a bug you also commented in #1235 , which is why I wanted to explain and test this.

than omit nowhitelist, blacklist-nolog and leave a short hint for read-only

[matu3ba]

@rusty-snake Please review. Is there anything essential missing?

[rusty-snake]

any later blacklist. -> any later blacklist/whitelist.

Common mistakes:

• blacklist PATH: PATH is still present, but not accessible (with whitelist they don't exist)
• noblacklist ~/Documents/presentations blacklist ~/Documents: didn't work
• whitelisting profiles: new files are not saved (=> don't use for text editors, image editing software, ... )

[matu3ba]

@rusty-snake Please review.
Did add your stuff. Did add a better explanation of profile precedence.

The template deserves a better place before the explanation.
Do shell commands have any special handling different from the profile?
Can you think of a better name that also mentions that profiles are explained here?

[rusty-snake]

Can you think of a better name that also mentions that profiles are explained here?

• Profiles
• about profiles
• working with profiles
• ...

Be aware that the local non-admin user may change ~/.config/firejail and depending on your setup you might need to restrict write access to that folder.

You can still run without firejail (/usr/bin/firefox) and use the commandline (firejail --noprofile firefox, firejail --profile=myprofiel.profile fierfox)

1. Be aware of correct use of read-only due to issue #1235.

fixed in master

1. Flexible adaptions belong into scripts/shell commands like firejail --whitelist=~/Downloads/thunderbird thunderbird for optionally allowance of appending data.

a common mistake?

The execution sequence is generally the following:

first cmd then recusive the profiles

[rusty-snake]

System-wide profiles for pull requests are supposed to be created in folder etc

I recommend not to use /etc as it is not relevant and you must be root to edit it.

[SkewedZeppelin]

I recommend not to use /etc

It should be reworded, I think they meant etc in the git repo.

[matu3ba]

@rusty-snake @SkewedZeppelin Thanks for the feedback. Included and changed the sections.
Did reorder the whole thing. What do you think of this ?

[matu3ba]

I think the phrase "persistent" might be problematic due to dependence on the commands.
Aside the common mistake 1. could be possibly shifted to the General section.

[matu3ba]

@rusty-snake @SkewedZeppelin Suggestion for finalization or closing from my side.

[rusty-snake]

@matu3ba https://github.com/netblue30/firejail/issues/2729#issuecomment-499022730

[MrFrank17]

Hello,

I am trying to create a profile for the pcloud client (www.pcloud.com) and need some help. If that is the wrong place to ask, please show me right the one :-)

My profile looks like that at the moment:
`protocol unix,inet,inet6,netlink,packet
noblacklist ${PATH}/fusermount
whitelist ${HOME}/.config/pcloud
whitelist ${HOME}/.pcloud
whitelist ${HOME}/.local/share/applications/appimagekit-pcloud.desktop
whitelist ${HOME}/.config/pulse
noblacklist ${HOME}/pCloudDrive

include default.profile`

When starting with --trace --debug I get a message: execv error: No such file or directory.

Also the client offers "drive access" without syncing by mounting the cloud to a local folder by default.
Even when starting with firejail --noprofile pcloud this seems not to work.

Has anyone created a profile for pcloud so far?

Thanks!

[rusty-snake]

If that is the wrong place to ask, please show me right the one :-)

Longer threads: open a new issue
Short (2-3 comments): use #1139

When starting with --trace --debug I get a message: execv error: No such file or directory.

From pcloud or firejail?

Even when starting with firejail --noprofile pcloud this seems not to work

You can try my noprofile. If the error stays pcloud is likely not firejailable.

noprofile

noprofile.profile

# 
# - env vars cleared
# - firejail.config
# - PID-namespace

allow-debuggers
allusers
# env FOO=bar
#keep-dev-shm
#keep-var-tmp
#noautopulse
writable-etc
writable-run-user
writable-var
writable-var-log

noblacklist /sys/fs
noblacklist /sys/module

[MrFrank17]

Thanks for your quick answer!
Even with your "noprofile" the mapping of the cloud to a local folder does not work. So yes, maybe pcloud is not firejailable. Or at least that functionality as the rest seems to work.

I had to call it without --trace. With that the application will not come up. It does not give any helpful error message. Is this there more to investigate about that?

[MrFrank17]

Another question:
I noticed that the application, which were not closed on logout and are therefore started automatically on login, are not firejailed unless I close and reopen them. Using KDE on Kubuntu 20.04. Is this something to report? If yes, please give me the link.

Thanks!

[rusty-snake]

Open a new issues for the KDE thing.

[MrFrank17]

Done!

Last question - sorry for bothering you:
When firejailed applications shall open other applications, (e.g. in KeepassXC clicking on the link of a website to open it in firefox) this is prevented for me. How can this be enabled?

[rusty-snake]

Thats still an documentation lack. For now I move you to #3471.

[bbhtt]

Is there a better way to audit Linux PS capabilities currently being used by a process other than pscap or getcap or bcc. Maybe include this in the wiki for caps.keep section https://www.andreasch.com/2018/01/13/capabilities/ https://en.wikibooks.org/wiki/Grsecurity/Appendix/Capability_Names_and_Descriptions

[NetSysFire]

I would like to rewrite some parts, especially Locations and Types, of this page because they are a bit unclear and should be a bit more simple imo.
Correct me if any of the statements below is wrong or needs improvement.

file types

Every file in a firejail dir (/etc/firejail, ~/.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
    
    
    
  
  

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, 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.

[rusty-snake]

Thanks for helping with the docs :1st_place_medal: :hugs: .

file locations

all right

file types

Every file in a firejail dir (/etc/firejail, ~/.config/firejail) is basically a profile. They all follow the same syntax.
However, there are still some different file types:

Right, I added these "profile-types" to better explain the differences how profile are used. (:nerd_face: There is one function differences: include foobar.local does not fail, while all others fail if they do not exist. :nerd_face: )

Regular profiles

• It contains settings for a specific application, like curl.profile

I would split it

• Regular (e.g. curl.profile)
• Alias (e.g. atom-beta.profile)
• Common (e.g. firefox-common.profile)

Overrides (.local)

all fine

Includes (.inc)

We could split it in whitelist, disable, special (feh-network.inc). However this is overkill IMHO.

[NetSysFire]

Just updated my comment to add these improvements

[rusty-snake]

LGTM

Every file in a firejail directory … is basically a profile.

There is one special: /etc/firejail/firejail.config.
However I don't think we need to talk about every special thing.

Includes that start with allow handle allowing access to certain paths.

We might want to clarify that this is only for blacklisting (by disable-*.inc). If a profile contains allow-python3.inc and private-bin foo,bar the python interpret is not available.

[Thaodan]

Is there a reason that preinstalled profiles go to /etc? Wouldn't it make more sense to ship them in /usr?

[NetSysFire]

I would like to add some more info about directives to the page, like this:

| directive | override support | explanation |
|---|---|---|
| include | :heavy_check_mark: | includes a file |
| quiet | :x: (issue link here) | less verbose output for a profile |

Perhaps it would make sense to add a few more columns, like a notes column which contains relevant issues or caveats. We could maybe even link to the source of the directive, but this may be overkill.
Because Firejail has lots of directives it might be better to even use a separate page.

There are of course the manual pages but I did not find any information about override support for specific directives for example.
What do you think about this?

[matu3ba]

Is there a reason that preinstalled profiles go to /etc? Wouldn't it make more sense to ship them in /usr?

/etc gradually became the configuration directory.

/usr is for source code and alike, which is why the github dev is placed on /usr.

For making things easy, it is just prefixed.

[matu3ba]

I would like to add some more info about directives to the page, like this:
directive override support explanation
include heavy_check_mark includes a file
quiet x (issue link here) less verbose output for a profile

Perhaps it would make sense to add a few more columns, like a notes column which contains relevant issues or caveats. We could maybe even link to the source of the directive, but this may be overkill.
Because Firejail has lots of directives it might be better to even use a separate page.

There are of course the manual pages but I did not find any information about override support for specific directives for example.
What do you think about this?

Graphical stuff is easier to understand, but you dont want to separate the directive from the support check marks (wasting space).
If there is a directive with override support, the command has a name/phrasing.
If not, there does not exist a name/phrasing.

[Thaodan]

Is there a reason that preinstalled profiles go to /etc? Wouldn't it make more sense to ship them in /usr?

/etc gradually became the configuration directory.

/usr is for source code and alike, which is why the github dev is placed on /usr.

For making things easy, it is just prefixed.

This not true or at least just half of it. Preinstalled/vendor config should go to /usr now days to be differentiated from system config.

[rusty-snake]

Is there a reason that preinstalled profiles go to /etc? Wouldn't it make more sense to ship them in /usr?

No real reason, but it would require code changes and would confuse unskilled users and outdated the most tutorials around the internet,

I would like to add some more info about directives to the page, like this:

It would be in large parts a duplication of the man-pages, I don't know if we are doing ourselves good with it.

override support

Since ignore include is supported, all command can be ignored (except condition?) including quite. The issue with quite is that it must be the first command, meaning in the most situations you can't ignore it from locals.