Handbook WG - Jails

[carlavilla]

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

[• karels]

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

239

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]

Finish the chapter

[• karels]

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

543–544

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.

556

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

598

This should use ${bridge}.

742–745

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.

772–774

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

[• karels]

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

543–544

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

[jrm]

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

127–128

146

154–155

171

187

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

196–198

198–203

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

219

225–226

228–231

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

229–230

235–239

253–256

258

[fernape]

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

92–93

into a different types --> into different types

123

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.

130

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

166–168

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.

171

Can we simplify the sentence too?

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

173

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

173

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.

198

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.

212–215

another directories --> other directories

271

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.

274

Officially --> In principle

Just a suggestion.

395

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

410

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

413

I would use inherit here too.

421

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

425–426

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

506–507

bridge --> man:bridge[4]

588

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

597–598

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

610

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

622

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 ,

626

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

service jail  ubuntu stop

or

service jail  ubuntu onestop

652

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.

664–665

will be used --> is used

665

jalil --> jail

679

classic --> classic

718

Same as above. Is this the preferred way?

What is -f?

739

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.

741

Drop then

757–758

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

785–788

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

[• karels]

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

135–136

s/host system's/template's/

136

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.

139

s/host system/template/

146

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".

173

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

173

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".

187

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

218

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.

269–270

I don't understand this sentence.

270

s/This/These/

271

How about ip6 addresses?

353

or jail.conf.d?

396

or jail.conf.d

410

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

430

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

435–436

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

444–446

OpenZFS again...

[carlavilla]

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

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

123

Removed, we have enough text in this chapter :)

136

Removed :)

146

Much better :)

171

Sure!

218

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

269–270

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

271

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

410

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

413

Changed here to show an example

561

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

598

good catch!

610

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

665

Good catch!

[carlavilla]

Fix all the comments :)
Thanks to all!