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

257

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

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.

708–709

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

746

This should use ${bridge}.

1043

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.

1088–1089

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

691

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

146–149

165–166

171–173

184

208

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

216–218

221–226

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

236

238

243–246

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

250

253

281–300

286

[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

109–110

into a different types --> into different types

143

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.

149

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

180

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.

184

Can we simplify the sentence too?

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

190

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

190

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.

221

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.

232

another directories --> other directories

330

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.

332–333

Officially --> In principle

Just a suggestion.

466

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

484

I would use inherit here too.

507

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

535

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

542–543

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

677

bridge --> man:bridge[4]

772

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

782

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

812

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

823–824

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 ,

828

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

service jail  ubuntu stop

or

service jail  ubuntu onestop

885–891

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.

923

will be used --> is used

925

jalil --> jail

950

classic --> classic

989

Same as above. Is this the preferred way?

What is -f?

1014

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.

1016

Drop then

1065–1066

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

1102

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

153–156

s/host system's/template's/

154

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.

157

s/host system/template/

165–166

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

190

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

190

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

208

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

235

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.

329

I don't understand this sentence.

330

How about ip6 addresses?

330

s/This/These/

364

or jail.conf.d?

467

or jail.conf.d

507

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

553

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

574–578

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

604

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

143

Removed, we have enough text in this chapter :)

154

Removed :)

165–166

Much better :)

184

Sure!

235

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

329

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

330

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

484

Changed here to show an example

507

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

710

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

746

good catch!

812

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

925

Good catch!

[carlavilla]

Fix all the comments :)
Thanks to all!