gitea-mirror commented

Owner

Originally created by @tredondo on GitHub (Mar 5, 2021).
Original GitHub issue: https://github.com/netblue30/firejail/issues/4049

I'm a semi-technical user and on one hand, firejail is pretty easy to use, so it should appeal to many users, but on the other, it uses some very technical terms right from the start, that may turn users off.

About/README

The "About" of this repo for example, is "Linux namespaces and seccomp-bpf sandbox". I have no idea what those are, esp. seccomp. This might scare off some users. Maybe a more general description would be better (e.g. "Firejail - sandbox console or graphical Linux applications"), followed by details in the README?

As a non-technical user, I would much rather see "per-directory access control to the filesystem", but I don't see that in the first 3 paragraphs of the README. "Mount tables" sounds vaguely like that, but that's an implementation detail, rather than a user-facing feature.

A "Features" section would be great. I really think that listing firejail's features at the top of the README could bring many more users to it, and the technical implementation details (whatever seccomp-bpf means) can follow underneath.

Documentation

The documentation is formatted as a man page. This is fine in the terminal, but on the web, this has a few problems:

no hyperlinks. For example, in firejail-profile, I'm not sure what "netfilter" is. Sounds like a firewall. A link would really help. (This could still be added while keeping the man format)
monospaced font is harder to read than proportional font, especially with justification:
no formatting (e.g. bold, italics, monospace/tty for arguments)
less mobile-friendly (useful for users evaluating firejail)

Examples

After some Googling, looks like netfilter can indeed be used to implement firewalling. This is IMO the most common networking profile restriction that a user would want. For example, an application should only be allowed to access a given host, and nothing else. Far more common than mtu or setting a different hostname for the sandbox. So an example for that would really help.

Originally created by @tredondo on GitHub (Mar 5, 2021). Original GitHub issue: https://github.com/netblue30/firejail/issues/4049 I'm a semi-technical user and on one hand, `firejail` is pretty easy to use, so it should appeal to many users, but on the other, it uses some very technical terms right from the start, that may turn users off. # About/README The "About" of this repo for example, is "Linux namespaces and seccomp-bpf sandbox". I have no idea what those are, esp. seccomp. This might scare off some users. Maybe a more general description would be better (e.g. "Firejail - sandbox console or graphical Linux applications"), followed by details in the README? As a non-technical user, I would much rather see "per-directory access control to the filesystem", but I don't see that in the first 3 paragraphs of the README. "Mount tables" sounds vaguely like that, but that's an implementation detail, rather than a user-facing feature. A "Features" section would be great. I really think that listing firejail's features at the top of the README could bring many more users to it, and the technical implementation details (whatever `seccomp-bpf` means) can follow underneath. # Documentation The documentation is formatted as a man page. This is fine in the terminal, but on the web, this has a few problems: * no hyperlinks. For example, in [firejail-profile](https://rusty-snake.github.io/firejail/features/man-firejail-profile.html), I'm not sure what "netfilter" is. Sounds like a firewall. A link would really help. (This could still be added while keeping the `man` format) * monospaced font is [harder to read](https://ux.stackexchange.com/questions/48753/does-the-use-of-monospaced-fonts-negatively-affect-legibility-of-article-text) than proportional font, especially with justification: ![image](https://user-images.githubusercontent.com/10043369/110054237-d6aafe80-7cfe-11eb-84ea-8df7a8b5eed0.png) * no formatting (e.g. bold, italics, monospace/tty for arguments) * less mobile-friendly (useful for users *evaluating* firejail) # Examples After some Googling, looks like `netfilter` can indeed be used to implement firewalling. This is IMO the most common networking profile restriction that a user would want. For example, an application should only be allowed to access a given host, and nothing else. Far more common than `mtu` or setting a different `hostname` for the sandbox. So an example for that would really help.

gitea-mirror added the

enhancement

documentation

labels 2026-05-05 09:11:52 -06:00

gitea-mirror commented

2026-05-05 09:11:54 -06:00

Author

Owner

@kmk3 commented on GitHub (Mar 5, 2021):

I'm a semi-technical user and on one hand, firejail is pretty easy to use,
so it should appeal to many users, but on the other, it uses some very
technical terms right from the start, that may turn users off.

About/README

The "About" of this repo for example, is "Linux namespaces and seccomp-bpf
sandbox". I have no idea what those are, esp. seccomp. This might scare off
some users. Maybe a more general description would be better (e.g. "Firejail

sandbox console or graphical Linux applications"), followed by details in
the README?

Having an additional explanation using simpler terms would be nice.

As a non-technical user, I would much rather see "per-directory access
control to the filesystem", but I don't see that in the first 3 paragraphs of
the README. "Mount tables" sounds vaguely like that, but that's an
implementation detail, rather than a user-facing feature.

Yes, this is a rather key feature of firejail and would be nice to have it
explicitly mentioned/a high-level explanation.

A "Features" section would be great. I really think that listing firejail's
features at the top of the README could bring many more users to it, and the
technical implementation details (whatever seccomp-bpf means) can follow
underneath.

Agreed.

Documentation

The documentation is formatted as a man page. This is fine in the terminal,
but on the web, this has a few problems:

no hyperlinks. For example, in
firejail-profile,
I'm not sure what "netfilter" is. Sounds like a firewall. A link would
really help. (This could still be added while keeping the man format)

monospaced font is harder to
read
than proportional font, especially with justification:

no formatting (e.g. bold, italics, monospace/tty for arguments)

less mobile-friendly (useful for users evaluating firejail)

(Possible duplicate of #2729)

To me it is important to have the documentation promptly available in the
terminal and, as you have noted, the problems raised are essentially a matter
of formatting in the html output. For some fancy conversion examples, the
following html pages were generated from the find(1) man page:

Since it's the version from GNU's coreutils (or "findutils" in this case), the
source is probably in groff and the output does have hyperlinks (e.g.: to other
man pages) throughout.

mandoc also supports all of the items. Examples from its own mdoc-written
documentation and from OpenBSD's documentation (which also uses mandoc),
respectively:

firejail-profile,

Note that this website is not official/released yet, and that the progress is
being tracked on #2729. Looking at the source code, the html file seems to be
generated from a markdown file, which contains just a text dump of the
formatted man page, wrapped in a code fence:

https://raw.githubusercontent.com/rusty-snake/firejail/4906551540196cc3f4a240b5715faf5ea7f45569/features/man-firejail-profile.md

I don't know how the roff to markdown conversion was done, but using groff
directly gives a rather normal-looking html page:

$ zcat /usr/share/man/man5/firejail-users.5.gz |
  groff -T html >firejail-users.5_groff.html

It has a non-monospaced font and formatting, but it does not appear to be
exactly mobile-friendly. It's also HTML4 (which I'm not sure how much it
matters in practice). There are no hyperlinks because they are not marked as
such on the roff source. Also, converting firejail-users(5) results in a
rather botched output (half of the page is bold):

$ zcat /usr/share/man/man5/firejail-profile.5.gz |
  groff -T html >firejail-profile.5_groff.html

I suspect that it may be due to an unproperly-formatted source. In that case,
the first step towards good-looking html output would likely be to fix the roff
input.

Additionally, another option would be pandoc:

$ zcat /usr/share/man/man5/firejail-users.5.gz |
  pandoc -T html >firejail-users.5_pandoc.html
[WARNING] This document format requires a nonempty <title> element.
  Defaulting to '-' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

It's HTML5 and it at least has this (for mobile friendliness, etc):

<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />

Though it appears to miss/ignore some elements and I'm not sure if it's due to
problems in the source or in the conversion.

@kmk3 commented on GitHub (Mar 5, 2021): > I'm a semi-technical user and on one hand, `firejail` is pretty easy to use, > so it should appeal to many users, but on the other, it uses some very > technical terms right from the start, that may turn users off. > > # About/README > > The "About" of this repo for example, is "Linux namespaces and seccomp-bpf > sandbox". I have no idea what those are, esp. seccomp. This might scare off > some users. Maybe a more general description would be better (e.g. "Firejail > - sandbox console or graphical Linux applications"), followed by details in > the README? Having an additional explanation using simpler terms would be nice. > As a non-technical user, I would much rather see "per-directory access > control to the filesystem", but I don't see that in the first 3 paragraphs of > the README. "Mount tables" sounds vaguely like that, but that's an > implementation detail, rather than a user-facing feature. Yes, this is a rather key feature of firejail and would be nice to have it explicitly mentioned/a high-level explanation. > A "Features" section would be great. I really think that listing firejail's > features at the top of the README could bring many more users to it, and the > technical implementation details (whatever `seccomp-bpf` means) can follow > underneath. Agreed. > # Documentation > > The documentation is formatted as a man page. This is fine in the terminal, > but on the web, this has a few problems: > > * no hyperlinks. For example, in > [firejail-profile](https://rusty-snake.github.io/firejail/features/man-firejail-profile.html), > I'm not sure what "netfilter" is. Sounds like a firewall. A link would > really help. (This could still be added while keeping the `man` format) > > * monospaced font is [harder to > read](https://ux.stackexchange.com/questions/48753/does-the-use-of-monospaced-fonts-negatively-affect-legibility-of-article-text) > than proportional font, especially with justification: > ![image](https://user-images.githubusercontent.com/10043369/110054237-d6aafe80-7cfe-11eb-84ea-8df7a8b5eed0.png) > * no formatting (e.g. bold, italics, monospace/tty for arguments) > > * less mobile-friendly (useful for users _evaluating_ firejail) (Possible duplicate of #2729) To me it is important to have the documentation promptly available in the terminal and, as you have noted, the problems raised are essentially a matter of formatting in the html output. For some fancy conversion examples, the following html pages were generated from the `find(1)` man page: * <https://man.archlinux.org/man/core/findutils/find.1.en> * <https://man7.org/linux/man-pages/man1/find.1.html> Since it's the version from GNU's coreutils (or "findutils" in this case), the source is probably in groff and the output does have hyperlinks (e.g.: to other man pages) throughout. [mandoc][1] also supports all of the items. Examples from its own mdoc-written documentation and from OpenBSD's documentation (which also uses mandoc), respectively: * <https://mandoc.bsd.lv/man/mandoc.1.html> * <https://man.openbsd.org/man.1> > [firejail-profile](https://rusty-snake.github.io/firejail/features/man-firejail-profile.html), Note that this website is not official/released yet, and that the progress is being tracked on #2729. Looking at the source code, the html file seems to be generated from a markdown file, which contains just a text dump of the formatted man page, wrapped in a code fence: <https://raw.githubusercontent.com/rusty-snake/firejail/4906551540196cc3f4a240b5715faf5ea7f45569/features/man-firejail-profile.md> I don't know how the roff to markdown conversion was done, but using groff directly gives a rather normal-looking html page: ```console $ zcat /usr/share/man/man5/firejail-users.5.gz | groff -T html >firejail-users.5_groff.html ``` It has a non-monospaced font and formatting, but it does not appear to be exactly mobile-friendly. It's also HTML4 (which I'm not sure how much it matters in practice). There are no hyperlinks because they are not marked as such on the roff source. Also, converting firejail-users(5) results in a rather botched output (half of the page is **bold**): ```console $ zcat /usr/share/man/man5/firejail-profile.5.gz | groff -T html >firejail-profile.5_groff.html ``` I suspect that it may be due to an unproperly-formatted source. In that case, the first step towards good-looking html output would likely be to fix the roff input. Additionally, another option would be pandoc: ```console $ zcat /usr/share/man/man5/firejail-users.5.gz | pandoc -T html >firejail-users.5_pandoc.html [WARNING] This document format requires a nonempty <title> element. Defaulting to '-' as the title. To specify a title, use 'title' in metadata or --metadata title="...". ``` It's HTML5 and it at least has this (for mobile friendliness, etc): ```html <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> ``` Though it appears to miss/ignore some elements and I'm not sure if it's due to problems in the source or in the conversion. [1]: https://mandoc.bsd.lv/ [2]: https://github.com/netblue30/firejail/issues/2729#issuecomment-724811241

gitea-mirror commented

2026-05-05 09:11:56 -06:00

Author

Owner

@rusty-snake commented on GitHub (Mar 5, 2021):

"Linux namespaces and seccomp-bpf sandbox"

are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect.

A "Features" section would be great.

👍 👍

The documentation is formatted as a man page.
Additionally, another option would be pandoc:

If did some research and testing for man-pages written in something more comfortable then (g)roff in the lat weeks, if we want, we can also switch to md/rst/ronn/pod/... as source and then convert it to groff/html/latex/...

Documentation for less technical users

Related: #2977

@rusty-snake commented on GitHub (Mar 5, 2021): > "Linux namespaces and seccomp-bpf sandbox" are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect. > A "Features" section would be great. :+1: :+1: > The documentation is formatted as a man page. > Additionally, another option would be pandoc: If did some research and testing for man-pages written in something more comfortable then (g)roff in the lat weeks, if we want, we can also switch to md/rst/ronn/pod/... as source and then convert it to groff/html/latex/... > Documentation for less technical users Related: #2977

gitea-mirror commented

2026-05-05 09:11:56 -06:00

Author

Owner

@tredondo commented on GitHub (Mar 7, 2021):

Thanks for addressing my suggestions, related question: where does the documentation for the Features page live?

I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR.

@tredondo commented on GitHub (Mar 7, 2021): Thanks for addressing my suggestions, related question: where does the documentation for the [Features](https://firejail.wordpress.com/features-3/) page live? I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR.

gitea-mirror commented

2026-05-05 09:11:58 -06:00

Author

Owner

@rusty-snake commented on GitHub (Mar 7, 2021):

where does the documentation for the Features page live?

On wordpress

I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR.

Not possible ATM you need to ping @netblue30 so he can update that page, read https://github.com/netblue30/firejail/issues/2713#issue-446368362.

@rusty-snake commented on GitHub (Mar 7, 2021): > where does the documentation for the Features page live? On wordpress > I found a typo there ("Located in /etc/firejal directory") but I don't know where to submit a PR. Not possible ATM you need to ping @netblue30 so he can update that page, read https://github.com/netblue30/firejail/issues/2713#issue-446368362.

gitea-mirror commented

2026-05-05 09:11:59 -06:00

Author

Owner

@netblue30 commented on GitHub (Mar 10, 2021):

@tredondo - just put it here in the discussion and I'll move it on wordpress. You will probably find a lot of them, most of us here are not native Engilsh speakers. Thanks.

@netblue30 commented on GitHub (Mar 10, 2021): @tredondo - just put it here in the discussion and I'll move it on wordpress. You will probably find a lot of them, most of us here are not native Engilsh speakers. Thanks.

gitea-mirror commented

2026-05-05 09:11:59 -06:00

Author

Owner

@rusty-snake commented on GitHub (Mar 10, 2021):

@netblue30 it's already here, /etc/firejal misses a i.

@rusty-snake commented on GitHub (Mar 10, 2021): @netblue30 it's already here, /etc/firejal misses a i.

gitea-mirror commented

2026-05-05 09:12:00 -06:00

Author

Owner

@netblue30 commented on GitHub (Mar 10, 2021):

I got it, thanks!

@netblue30 commented on GitHub (Mar 10, 2021): I got it, thanks!

gitea-mirror commented

2026-05-05 09:12:00 -06:00

Author

Owner

@tredondo commented on GitHub (Sep 26, 2021):

"Linux namespaces and seccomp-bpf sandbox"

are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect.

I came back to firejail after half a year, and still have absolutely no idea wtf seccomp-bpf is :) And the README still starts with that gibberish.

@tredondo commented on GitHub (Sep 26, 2021): > > "Linux namespaces and seccomp-bpf sandbox" > > are used by every (user-space) sandbox program for Linux (firejail, bubblewrap, minijail, ...). So the info is that what a technical user would expect. I came back to firejail after half a year, and still have absolutely no idea wtf seccomp-bpf is :) And the README still starts with that gibberish.

gitea-mirror commented

2026-05-05 09:12:01 -06:00

Author

Owner

@tredondo commented on GitHub (Oct 29, 2024):

Back to firejail after 3 years and it's still cryptic.

Maybe the core team doesn't care about attracting more users?

Maybe they just need a reminder?

Here's a practical one: briefly explain in the README what the deal is with AppArmor vs. SELinux. Users may think it's another security layer/module they can compile support for, and waste time installing libraries to compile support for it, when it may not be supported by their OS.

Seeing the little traction this issue has received, I went ahead and edited the README - #6524. Feel free to fix the obvious mistakes I probably made.

@tredondo commented on GitHub (Oct 29, 2024): Back to firejail after 3 years and it's still cryptic. Maybe the core team doesn't care about attracting more users? Maybe they just need a reminder? Here's a practical one: briefly explain in the README what the deal is with AppArmor vs. SELinux. Users may think it's another security layer/module they can compile support for, and waste time installing libraries to compile support for it, when it may not be supported by their OS. Seeing the little traction this issue has received, I went ahead and edited the README - #6524. Feel free to fix the obvious mistakes I probably made.

gitea-mirror referenced this issue

2026-05-05 10:18:48 -06:00

[PR #2515] [MERGED] Fix private-lib in regextester profile #4370

Rows
Columns

[GH-ISSUE #4049] Documentation for less technical users #2515

About/README

Documentation

Examples

About/README

Documentation