kmk3
commented
3 years ago I'm a semi-technical user and on one hand,
firejailis 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-bpfmeans) 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
manformat)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:
- 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 also supports all of the items. Examples from its own mdoc-written documentation and from OpenBSD's documentation (which also uses mandoc), respectively:
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:
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.htmlIt 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.htmlI 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.
rusty-snake
tredondo
netblue30
I'm a semi-technical user and on one hand,
firejailis 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-bpfmeans) 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:
manformat)Examples
After some Googling, looks like
netfiltercan 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 thanmtuor setting a differenthostnamefor the sandbox. So an example for that would really help.