Page MenuHomeFreeBSD

Handbook WG - Jails
ClosedPublic

Authored by carlavilla on Aug 14 2023, 4:39 PM.
Tags
None
Referenced Files
Unknown Object (File)
Wed, May 15, 12:39 PM
Unknown Object (File)
Fri, Apr 26, 1:26 AM
Unknown Object (File)
Apr 17 2024, 5:50 AM
Unknown Object (File)
Mar 22 2024, 7:49 PM
Unknown Object (File)
Mar 22 2024, 7:49 PM
Unknown Object (File)
Mar 1 2024, 4:26 PM
Unknown Object (File)
Feb 7 2024, 12:23 AM
Unknown Object (File)
Jan 29 2024, 2:40 PM
Subscribers
None

Details

Summary

Rewrite jails chapter

The idea of this rewrite is to explain how to work with "raw" jails

  • Explain the 4 types of jails: thick, thin, vnet and linux
  • Explain how to create the file structure for jails
  • Explain the jail.conf configuration file and its different parameters
  • Explain how to create a thick jail
  • Explain how to create a thin jail with ZFS snapshots and using NullFS
  • How to handle jails, boot, reboot, delete, etc.
  • List the jails
  • Execute commands in jail
  • Access the console of a jail
  • List the different jail managers that exist

Output: https://people.freebsd.org/~carlavilla/handbook-wg/jails.html

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
documentation/content/en/books/handbook/jails/_index.adoc
261

In the following block of commands, the string "zroot" at the beginning of the dataset name should be the name of the base zfs filesystem. bsdinstall uses zroot, so this is literally correct in that case, but I have multiple filesystems including "zpool" and "zpools". Maybe "In the following commands, replace zroot with the file system name if it is different."

carlavilla retitled this revision from Handbook WG - Jails - WIP to Handbook WG - Jails.

Finish the chapter

These comments are from reviewing from the VNET jail section to the end. I'll make another pass from the beginning later on.

documentation/content/en/books/handbook/jails/_index.adoc
691

It doesn't need an IP; does it serve any purpose? It works fine without one. Note, though, that "up" is needed when there is no IP. Also note that the ifconfig command has "init" duplicated.

710

s/Both/Either/, and this sentence should probably all be on one line.

752

This should use ${bridge}.

1042

It is probably worth mentioning that the install step is run twice because it does only the kernel on the first invocation, and the rest the second time. Also, I'd recommend another restart at the end to start all the daemons with any new binaries and libraries.

1080

I would definitely do another restart after the second install in this case, you can be sure that libraries and daemons would be updated.

documentation/content/en/books/handbook/jails/_index.adoc
691

Autocorrect again; that's "inet" that's duplicated.

I'm submitting now after only making it about a third of the way through because I may not be able to get back to this soon. Overall, it reads well to me.

documentation/content/en/books/handbook/jails/_index.adoc
141
162
167
180
206

"ways of configuration" sounds a little strange to me.

214–216
219–224

This is my attempt to make this section concise without losing much critical information.

238
241
246–249

Is -p necessary? You already created the parent dataset above.

254
257
271
276

OK,

My take on this. Some comments might be opinionated. Specially the ones that are more cosmetic.

documentation/content/en/books/handbook/jails/_index.adoc
103

into a different types --> into different types

137

I don't think this paragraph belongs here in the "Thin Jails" section.
I would remove it or add a table with pros and cons for the 4 types of jails described before.

144

I would remove this point. The disk space usage reduction is already mention in the first item.

176

uses OpenZFS or UFS as the file system. --> uses OpenZFS or UFS as file system.

I would drop the but I might be wrong here.

180

Can we simplify the sentence too?

The FreeBSD version running in the jail can not be newer that the version running in the host

186

Shorter: The man:jail[8] utility manages jails.

188

This is actually not true :-)

This works as any other service (or many of them): if the service is in /etc/rc.conf, you can use start, stop, etc.
If it is not, you must use onestart, onestop...

I don't have the jail service in /etc/rc.conf because I don't use jails every time I boot.
I just use the one* commands when needed.
Activating the jail service means that jails will be automatically booted.
Some people might not want that.

219

For consistency:

Netgraph (man:netgraph[4]) is a kernel --> man:netgraph[4] is a kernel

In general, we don't mention features and then write the link in parenthesis, we just name the thing.

234

another directories --> other directories

315

If ip4.addr = inherit then the jail inherits the address of the host.
This is usually sufficient and makes the jail work even if the host ip address changes.
I can't find were this is documented though.

330

Officially --> In principle

Just a suggestion.

474

The last step will be --> The last step is

497

I would use inherit here too.

517

The first step will be --> The first step is

545

With the userland extracted in the templates directory, will be necessary --> Once the userland is extracted n the templates directory, it will be necessary

553

With the files moved to the template, the next thing --> The next thing

677

bridge --> man:bridge[4]

774

without rebooting executing the --> without rebooting by executing the

784

With the machine created --> Once the machine has been created

814

A brief introduction of man:jexec[8] might be nice.

Also, I don't see the -f option in the manual page.
If the goal is going inside the jail as root, I think

jexec -u root ubuntu

should be enough

825

When the process has finished and is displayed on the console Base system installed successfully, --> When the process has finished and the message Base system installed successfully is displayed on the console ,

830

This removes the jail. Do we want that or do we want to do

service jail  ubuntu stop

or

service jail  ubuntu onestop
887

I would simplify this with something like:

Once the jail is created, there are a number of operations that can be performed like starting, rebooting or deleting the jail, installing software in it, etc.

925

will be used --> is used

927

jalil --> jail

952

classic --> classic

991

Same as above. Is this the preferred way?

What is -f?

1016

I would split this:

Jails *must be updated from the host* operating system.
The default behavior in FreeBSD is to disallow the use of man:chflags[1] in a jail.
This will prevent the update of some fails so updating from withing the jail will fail.

1018

Drop then

1058

the vast majority --> the majority

it is very easy to update them --> they are very easy to update

I would separate the above and below with a full stop.

it will be enough to keep the template updated. --> it is enough to update the template

1094

This line renders weirdly: rctl -a is in a line and the rest in the next line.

I think I have been through the whole chapter in this version now. A bunch of little stuff noted.

documentation/content/en/books/handbook/jails/_index.adoc
149

s/host system's/template's/

150

This doesn't seem to be true; using a template, the jail doesn't share with the host system. It is possible to have multiple templates of different versions.

153

s/host system/template/

162

I agree with splitting this, but I don't think VNET jails are "primarily" a network configuration mechanism; they have all the attributes of other jails as well. Maybe change "are primarily" to "add".

186

In addition, jail(8) doesn't really create or remove jails; it starts them or stops them. The proposed change avoids that confusion.

188

Although this is true, it is simpler to describe just one way of starting jails. My guess is that most people will want jails started at boot. Maybe we shouldn't use the word "necessary" though, or just change "activate" to "start".

206

Sounds better, but maybe change "two" to "several" (including netgraph, which is in this list).

237

What is releases for? I don't understand why media, releases, and templates would all be needed. I don't see any use of releases in the instructions. Note, if you delete it, it appears as a zfs create and a mkdir below.

315

How about ip6 addresses?

323

I don't understand this sentence.

324

s/This/These/

367

or jail.conf.d?

475

or jail.conf.d

517

But this shouldn't be here, it is the nullfs section.

563

Again, OpenZFS in the nullfs section; just remove it.

590

I don't understand why the skeleton directory is used. Maybe a sentence of explanation?

606

OpenZFS again...

Fixed all, I'm gonna upload the diff in a 15 minutes or so

documentation/content/en/books/handbook/jails/_index.adoc
137

Removed, we have enough text in this chapter :)

150

Removed :)

162

Much better :)

180

Sure!

237

I added it at the first beginnings of rewriting the chapter, but in the end I discarded it, removed :)

315

Done, I put the list of values in the ip4.addr entry instead of touching the example.

323

I have deleted it, you are right, it is unnecessary

497

Changed here to show an example

517

No, at the end you can use NullFS no mater if you're using OpenZFS or UFS.

716

This is true, but I prefer to make a section explaining the configuration file and then use a custom configuration for each kind of jail

752

good catch!

814

I changed, the -f option is for the login command

927

Good catch!

carlavilla marked 13 inline comments as done.

Fix all the comments :)
Thanks to all!

This revision was not accepted when it landed; it landed in state Needs Review.Sep 20 2023, 8:33 AM
This revision was automatically updated to reflect the committed changes.