Our documentation

[Fred-Barclay]

Hi folks
While @netblue30 has done a great job with documentation, I’m wondering if we can do better?

(Also, man pages can be frightening for newbies – let’s forget we have those for a moment!)

In my opinion, there are a few issues with our current docs system:

1. It depends on a single person and either creates a lot of work for that person, or falls behind.
2. It’s not comprehensive and (to me) a bit confusing. Where, for example, in this sidebar screenshot would I go to find out how to use --cgroup? (Which, by the way, is only documented in the man pages and the 0.9.20 release notes.)
   

• What about how to configure firejail with firejail.config vs globals.local vs <profile_name>.local vs custom profiles in ~/.config/firejail?
• What is /etc/firejail/firejail.users? Should someone edit it by hand?
• What about learning how to use --net= and --protocol=? It's there, just not obvious IMHO.

3. It’s not particularly robust. What I mean is, it doesn’t reflect new features or the deprecation of old ones easily. What might have been a good way to do something in firejail 0.9.36 is quite possibly not the best way to do it in 0.9.56 – or may not even exist at all!

private-bin for instance has gotten more powerful over time with globbing and so on, but some folks are still using older versions that are still supported, but don’t support private-bin globbing. If documents show globbing, it’ll mess up folks who use the older versions, but if they don’t, then a very useful feature is undocumented
(This is just an example, and not that great of one either!).

4. It’s a tad un-organised IMHO. This relates to my second point.
   Also, while comments might be useful, they have the effect of spreading documentation thin. If someone asks how to do something, we might answer in the comments, but that’s not a good way of documenting features.
   Also this leads to bugs and support requests being reported there, while IMHO we should have one, and only one, obvious spot for these – here! 😄

Instead, I propose that we consider sites like Read The Docs. This gives us multiple advantages:

1. Features are documented for all time! We can have multiple versions up – for example, 0.9.44 docs and 0.9.56 docs at the same time. That way folks on different versions can always have the documentation that’s tailored to their specific version. And, it'll be really easy to link people to the exact docs they need.
   This might sound overwhelming but I’m not actually proposing we go back and write separate documentation for all versions. Starting now and keeping 'em updated is fine by me (unless someone gets bored and really wants to document more! 😝) . And besides…

2. It’s all .md and .rst files! It’ll be easy to edit them incrementally as we add features and deprecate others. We won’t have to literally write separate docs for each new version of firejail, just make a new branch and edit as development happens, then push out as the latest doc version when each new version of firejail is released.

3. It’s all git on the backend (not literally). We’d just need to make a new repo here and then commit the docs. Readthedocs connects to GitHub so publishing them should be easy. This is rather simple and lowers the entry barrier, which leads me to…

4. It’s community editable, or sort of. This won’t be a wiki where anyone can edit – folks would have to clone the docs repo and send a pull request for review, just like they do for the firejail code. But it’s still rather simple and means anyone can contribute and fix typos, add more details, and so on; instead of being reliant on just a few chaps (@netblue30 only at the moment, as far as I’m aware).

Of course there are a few potential drawbacks. The biggest I see is that people won’t be able to comment for clarification, but that’s also an advantage in my opinion as I mentioned above. There are ads, but there are also ads on the wordpress site we use (I believe, I use a blocker so I don’t actually see them). We also wouldn’t have ultimate control of the docs, since we’d be relying on readthedocs for hosting. But we already rely on wordpress I believe, so this shouldn’t matter, plus they'll be distributed nicely thanks to git clone.

Thoughts?

Cheers!
Fred

[netblue30]

OK, let's make readthedocs the official documentation site for firejail. I have no idea what we need to do to set it up, so let's make @Fred-Barclay the boss. Once is started I'll clean up the wordpress site. Over there we need only release announcements, download links, some simple docs for beginners, videos and blogs.

[reinerh]

What are the plans then for the manpages?
At least I find them useful and I think many advanced users are likely to look something up there first.

I like the idea of having also more beginner-friendly documentation online, and also for different versions.
You suggested another repository for that. Could the .rst/.md files also be kept in this repository to make distribution within the source tarballs easier?

[chiraag-nataraj]

@reinerh I think this is more in lieu of the documentation currently on the firejail website. As I understand it, this will not replace the man pages.

[Fred-Barclay]

Alrighty then, I'll get started. 😄
@reinerh the man pages stay, no worries. As @chiraag-nataraj said, this is just for online documentation.
Also I've realised that we will in fact need the docs in this repo in a docs/ folder, not in a separate repo.

[chiraag-nataraj]

@Fred-Barclay I'd love to help get this up and running!

[Fred-Barclay]

@chiraag-nataraj Thanks -- that would be great! I'll make sure I get what I've done so far (which isn't much) up by Friday at the latest. Had some plans change unexpectedly since my last comment here so I've not been able to put in as much time as I expected. 😉

[ghost]

My man-page gripes:

--blacklist=dirname_or_filename
              Blacklist directory or file.

Obviously we're blacklisting something, but what does it mean to blacklist something? What's the difference between being blacklisted and not being whitelisted? Man page should make this clear. Also, to have dirname_or_filename on the right hand side with underscores is not a good style because underscores imply code or something literal. I would replace the underscores with spaces and put the RHS in angle brackets.

--debug-blacklists
              Debug blacklisting.

              Example:
              $ firejail --debug-blacklists firefox

Okay, but what does it mean to debug when the example gives no sample output? To some this could imply stepping through something. It's already evident from the option that we are debugging blacklists. It'd be more clear to say "enable verbose output to list blacklisted elements".

--env=name=value
              Set environment variable in the new sandbox.

              Example:
              $ firejail --env=LD_LIBRARY_PATH=/opt/test/lib

We could use an example for unsetting a variable. Would also be useful to mention that all variables in the parent scope are inherited by the sandboxed shell if that's indeed the case.

--noblacklist=dirname_or_filename
              Disable blacklist for this directory or file.

Should also mention what the effect of this is. Does it mean we have write permission or just read permission? I'm guessing read permission because profiles often noblacklist something and then follow that with whitelisting. An example showing that case and stating that it's to grant write access would help. (side note: why doesn't --whitelist imply --noblacklist? And why doesn't --whitelist=/var/log imply --whitelist-var?).

--whitelist=dirname_or_filename
              Whitelist directory or file. A temporary file system is mounted on the top directory, and the whitelisted files are mount-
              binded inside. Modifications to whitelisted files are persistent, everything else is discarded when the sandbox is closed.
              The top directory could be user home, /dev, /media, /mnt, /opt, /srv, /var, and /tmp.

              Symbolic  link handling: with the exception of user home, both the link and the real file should be in the same top direc‐
              tory. For user home, both the link and the real file should be owned by the user.

              Example:
              $ firejail --noprofile --whitelist=~/.mozilla
              $ firejail --whitelist=/tmp/.X11-unix --whitelist=/dev/null
              $ firejail "--whitelist=/home/username/My Virtual Machines"

Seems to say gives write permission in a very low-level way of saying it. I would keep the detail but replace the obvious and redundant "Whitelist directory or file" with "grant write permission on a file or dir". Also, it's important to say that --whitelist does not work without --whitelist-var in the case of /var/. An example that combines the two would be good.

--trace
              Trace open, access and connect system calls.

Needs to say something like "not compatible with --tracelog."

--tracelog
              This option enables auditing blacklisted files and directories. A message is sent to syslog in case the file or the direc‐
              tory is accessed.

Needs to say something like "not compatible with --tracel."

[SkewedZeppelin]

@libBletchley you've got a lot of questions

• there is no --whitelist-var only --writable-var
• there are two main types of profiles: blacklist and whitelist
  • blacklist removes access to most other program and sensitive files, but leaves everything else accessible
  • whitelist prevents all access except for what is whitelisted
    • all official profiles contain noblacklist in whitelist profiles to allow them to be easily converted from whitelist to a blacklist profile if the user wants a less strict profile. See Why do we have blacklist, noblacklist, and whitelist in the same profile? #1569 and [Proposal] Convert all profiles to a whitelist model #2070
• trace is more of a debugging/profile writing feature, whereas tracelog is meant to be always on if possible

[Vincent43]

@libBletchley man contributions welcome 😄

[ghost]

I was happy to bark out orders because I thought we were all piling the work on @Fred-Barclay. So it seems I've been tricked.

[Fred-Barclay]

Bwahaha! I haven't touched this in too long -- it's still something I want to get in but I just haven't had the time. :(

[chiraag-nataraj]

Let's move the discussion over to #2729.