Resources to learn how to debug firejail

[cameronj86]

The impression I've gotten so far is that that debugging firejail requires an existing mental model of Linux's innerworkings.

In lieu of that experience, is there a guide/tutorial that speaks to the typical "if this then (likely) that" troubleshooting approach for others?

If anyone has any resources that helped them out, please share!

[kmk3]

The impression I've gotten so far is that that debugging firejail requires an
existing mental model of Linux's innerworkings.

Do you mean using a debugger or just debugging profiles in general?

In lieu of that experience, is there a guide/tutorial that speaks to the
typical "if this then (likely) that" troubleshooting approach for others?

If anyone has any resources that helped them out, please share!

Do you have some specific examples of issues?

We have some related wiki pages, but they are not very comprehensive:

• https://github.com/netblue30/firejail/wiki/Troubleshooting
• https://github.com/netblue30/firejail/wiki/Debugging-Firejail

If you have some useful tips, resources or debugging steps, feel free to add to
the wiki.

If there is an issue directly related to a command, it might make sense to add
a note about it to the command description in the man pages.

See for example this recent PR:

• docs: clarify --private bug in man pages #6805

[cameronj86]

Thanks for the links!

Do you have some specific examples of issues?

My main friction point so far is that there's very little material on "how to troubleshoot" when things don't go as expected. Seeing a wall of config options is overwhelming when you don't know what is broken or how to fix it. Documentation might help around:

• Where to look when troubleshooting (I definitely was looking in journalctl and for a firejail db initially)
• What commands to use to troubleshoot look for - I used --debug to troubleshoot initial but gave up after skimming +200 lines and realizing I didn't know what I was looking for. in retrospect, based on your suggestion from my open ticket, I would have been better suited using --strace=stract.txt it sounds like? if so, the command could be more prominent in the docs.
• There are examples of putting together a profile... perhaps there can be one on troubleshooting a profile. Remove a capability, block a required path, block the dbus, etc so that there's a clear example of how to tackle this.

Some constructive feedback is that the documentation can be curated to be more digestible to those new to the project:

1. The man page experience for a newbie trying to understand the project is: Description -> Usage -> +30 pages of Options -> Desktop Integration -> Examples -> 5 more pages of nuanced explanations. Restructuring the man pages so that Examples and Desktop Integration are more prominently featured would go a long way w/ new user experiences IMO.
2. I'm guessing that firejail --help is so verbose so that power users can pipe grep it for quick answers? One suggestion is to keep the Examples section of it, move everything else to an --options, and repurpose --help to utilize the troubleshooting wiki.

It's clear that the project cares about new users, which is why firecfg, firejail-ui and firetools exists. I do think the middle ground between GUI newbie and savvy sandboxer could be improved. There's only one other game in town really and they aren't focused on educating users much either AFAICS, so the majority of end users are going to need their hand held a bit more to make sandboxing a bit more digestible and a bit less SUID/seccompf-bpf/+30 pages of options before examples are listed.

[kmk3]

Thanks for the links!

Glad they helped.

Do you have some specific examples of issues?

My main friction point so far is that there's very little material on "how to
troubleshoot" when things don't go as expected. Seeing a wall of config
options is overwhelming when you don't know what is broken or how to fix it.
Documentation might help around:

• Where to look when troubleshooting (I definitely was looking in journalctl
  and for a firejail db initially)
• What commands to use to troubleshoot look for - I used --debug to
  troubleshoot initial but gave up after skimming +200 lines and realizing I
  didn't know what I was looking for. in retrospect, based on your suggestion
  from my open ticket, I would have been better suited using
  --strace=stract.txt it sounds like? if so, the command could be
  more prominent in the docs.
• There are examples of putting together a profile... perhaps there can be
  one on troubleshooting a profile. Remove a capability, block a required
  path, block the dbus, etc so that there's a clear example of how to tackle
  this.

That makes sense; if you can help with any of these (such as the second point),
feel free to add to the wiki.

Some constructive feedback is that the documentation can be curated to be
more digestible to those new to the project:

1. The man page experience for a newbie trying to understand the project is:
   Description -> Usage -> +30 pages of Options -> Desktop Integration ->
   Examples -> 5 more pages of nuanced explanations. Restructuring the man
   pages so that Examples and Desktop Integration are more prominently
   featured would go a long way w/ new user experiences IMO.

There is a WIP attempt for firecfg in #6677 (and I have another WIP branch that
attempts to clarify the part about desktop integration in the man pages), but
the wiki and overall guidance could be improved regardless.

2. I'm guessing that firejail --help is so verbose so that power users can
   pipe grep it for quick answers? One suggestion is to keep the Examples
   section of it, move everything else to an --options, and repurpose --help
   to utilize the troubleshooting wiki.

--help is just intended to list the command options, as with other CLI
programs. The output is also automatically used for the bash completion.
Maybe a link to the wiki could be added to the output.

It's clear that the project cares about new users, which is why firecfg,
firejail-ui and firetools exists. I do think the middle ground between GUI
newbie and savvy sandboxer could be improved. There's only one other game in
town really and they aren't focused on educating users much either AFAICS, so
the majority of end users are going to need their hand held a bit more to
make sandboxing a bit more digestible and a bit less SUID/seccompf-bpf/+30
pages of options before examples are listed.

Yes, that would be helpful.

Though note that many details are obvious to those that are already used to it,
so newer users might be better equipped to notice and improve the documentation
for the parts that are less immediately obvious.

Also, there are usually more things to do than there is time and most active
developers are usually working on something other than documentation, so it
would be helpful to have more people researching how things work and
documenting them.

[cameronj86]

Appreciate you taking the time to respond. I have been jotting down notes and will add it to the wiki which can then be vetted, and corrected where needed.

[cameronj86]

Stumbled across these two articles w/ useful examples beyond the introductory commands:

• Some debugging steps in this article: https://debugging.works/blog/debugging-firejail/
• Kicking the tires w/ examples: https://snikt.net/blog/2016/02/25/firejail-chroot-on-speed/