Created attachment 234299 [details] patch with email headers and commit message In the Jails chapter of the handbook, the concept of mounting devfs in a jail is introduced under "To build and install a Jail from source." If a reader installs from the Internet or an ISO instead of from source, they might skip that section. Then, the next section, "Configuring the Host," uses the devfs_ruleset and mount.devfs arguments. Readers skipped the section about installing from source haven't learned these arguments yet. This issue tripped me up the first time I read the chapter. Attached is a patch with the following changes: 1. Remove the mount.devfs line from "To build and install a Jail from source." As of FreeBSD 12.3, it's gone from the cited man page example, anyway. 2. Move the explanation for that line to "Configuring the Host," building on the idea of replicating a real FreeBSD system in the jail. 3. Update the explanation to mention that a reasonable default ruleset is used if devfs_ruleset is not defined. There are a few other points I didn't address. For example, "doing nasty stuff" is a little dubious, and the jail(8) man page has some other deltas with "To build and install a Jail from source." I'd be happy do some more work here or in a separate patch if you think these are important to fix. This is my first time submitting a patch here. I'm a bit confused about the best way to do so, so I've two copies, one with email headers and commit message and one as plain diff in a .txt file. Thanks for considering!
Created attachment 234300 [details] patch diff as txt file
Created attachment 237282 [details] 2022-10-13 updated patch as plain diff Updating this patch to incorporate a suggestion kevans made on Discord: change "Most applications" to "Many applications." Reasoning was that there's no evidence for "Most" or "almost all" as in the published version.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=612b7cc1721224c494c5b2600188e1508bb5611b commit 612b7cc1721224c494c5b2600188e1508bb5611b Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2023-09-20 08:15:40 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2023-09-20 08:15:40 +0000 Handbook - Jails: Rewrite the chapter Changes: - Add jail types info: Thick, Thin, VNET and Linux Jails - Add info about the necessary configuration on the host system - Add info about types of networking in the jails - Explain the jail config file - Add info about how to configure Thick, Thin, VNET and Linux Jails - Explain how to upgrade the different types of jails - Add info about the resources limits in a Jail - Add info about different jail managers and containers Information obtained from: - https://man.freebsd.org/cgi/man.cgi?query=jail&sektion=8 - https://wiki.freebsd.org/Jails - https://man.freebsd.org/cgi/man.cgi?rctl(8) - https://vermaden.wordpress.com/2023/06/28/freebsd-jails-containers/ - https://clinta.github.io/freebsd-jails-the-hard-way/ - https://jacob.ludriks.com/2017/06/07/FreeBSD-Thin-Jails/ - Jails and VNET a guide - Derik J. Ramirez - https://wb-hk.blogspot.com/2016/04/freebsd-jails-4-thin-jails-using-nullfs.html - https://blog.uidrafter.com/freebsd-jails-network-setup - https://forums.freebsd.org/threads/setting-up-a-debian-linux-jail-on-freebsd.68434/ - https://github.com/msimerson/Mail-Toaster-6/wiki/Linux-Jails - https://etherealwake.com/2021/08/freebsd-jail-networking/ - https://wiki.freebsd.org/TomMarcoen/JailNetworking - https://weblog.antranigv.am/posts/2020/06/vnet-jail-howto/ PR: 203641, 200905, 209157, 248150, 263330, 264317, 226282, 239861, 166358, 178221, 265410 Reviewed by: karels@, fernape@, jrm@ Differential Revision: https://reviews.freebsd.org/D41450 .../content/en/books/handbook/jails/_index.adoc | 1492 ++++++++++---------- 1 file changed, 715 insertions(+), 777 deletions(-)
I'm gonna mark this as overcome by events since the chapter has been rewritten in: https://cgit.freebsd.org/doc/commit/?id=612b7cc1