Handbook Jail Chapter rewrite available for critique

[Fbsd8]

Andreas Nilsson wrote:

> Great! There really was a need to modernize the handbook with regards to
> jails. Since I'm not a native English speaker I'll leave grammar and
> spelling for those who are ;)
> 
> My first impressions are along the lines:
> To much scripts, to few examples/scenarios. Our users are smart, show them
> what can be accomplished with "high-level" config, leave minutiae to some
> part of the appendix.

The complexities of a a third generation jail system is imposable to 
explain from the command line. This is already stated in the document. 
Scripts are a more modern way to cover the over all subject without 
getting bogged down entering command line commands that the operater can 
make mistakes and typos and have to start from the begining just to 
continue.
> 
> Also the exclusion of zfs and vnet is surprising, as those really make
> jails shine, imo ( although jails really need to be thought about the
> "gray" area visa-vi networking in rc-scripts that vnet provides ). How
> about the resource control, which further makes jails really spiffy.

Well lets start with what the documents says about vnet. Its 
"experimental". I tried to compile it into my test bed 9.1 kernel and 
the system panicked on first boot. Now really, lets get serious here. 
Why would I include something that is so obvious not ready for prime 
time?. There is no way it should be used in a production jail system 
securing processes exposed to the public internet. It's a use at your 
own risk application. Maybe down the road when it grows up I will 
consider adding a sub-chapter about it. But for now its a dead subject.

ZFS, Here is another software application just newly introduced as 
experimental a few years ago. I admit it has come a long way in a short 
time and is now included in the base system. But its a very big animal 
and the handbook zfs chapter needs a lot more usage information first. 
The jail chapter is not the place to be documenting how to utilize zfs. 
Lets clear up some mis-conceptions. Jails can run on any host that has 
part or all of it's hard drive space under zfs control. It has no effect 
on the jail filesystems, matter of fact the jail system is totally 
un-aware it's on a zfs system. Mounting zfs spaces to the jail 
filesystem can be done from the host right now. The new jail.conf 
definition statements has the allow.mount.zfs parameter which allows the 
running jail to mount zfs space already defined within the running 
filesystem. It's my understanding it does not allow mounting zfs space 
from outside of the jailed filesystem. jail.conf does have some exec.* 
parameters for issuing commands to the host during the jail start 
process. zfs users have used these to automate mounting zfs data space 
to a jail's filesystem before the jail really comes to life. It's all in 
the jail(8) man page. I leave it up to the jail administrator to manage 
zfs for jail systems. Again it's not the jails job to manage zfs.
> 
> I would have preferred top-level separation of the different methods, ie
> after the introduction there was one "track" manual, one for old-school
> rc-, one for new-school rc- and one for jail.conf-style jails.
> 
> 
> More specifically I agree with Isaac Levy's, especially in regards to the
> "jail cell" terminology:
> 
> "16.1 Synopsis": the term jail cell is used, long before being defined.
> 
> "16.2 Introduction": Mentioning jail cells in a historic contest is imho a
> "blatant" lie ( they were never known as such ). As far as I know, no
> official documentation has called them cells, either. That does not mean
> that it's not an appropriate term, though. As a contrast there is Solaris
> vocabulary of zones ( "cells" ) and global zone ( "jail system" ). In this
> regard I prefer the solaris one.
> Most importantly, a large chunk of 16.2 would imo fit much better as a
> "history"-appendix. Current and new users don't need to know and consider
> the limitations of earlier implementations. The "generations" talked about
> could perhaps be quantified with a release version :)

Read this section again. it's not meant to be a history lesson. it's 
meant to expose the reader to the progress of the chroot and how the 
jail filesystem of that time affected performance and ease of use, 
leading up to the third generation jail filesystem documented in the new 
jail chapter.
> 
> There are, as stated by Isaac Levy, many (good) utils for managing jails.
> Why the focus on qjail? I also think that most of the strong points of
> jails are rendered moot without, in order, zfs and vimage. Linux jails
> might also interest quite a few people.

For real, Linux jails documented in the FreeBSD handbook? You have to be 
joking. Give qjail a ride and you will see that it's light years ahead 
of any of those ports you speak of.
> 

You really have to take time and digest what you read. It has to be read 
as a whole not as some limited selection of parts. It will all make 
sense after a few reads.

Thanks for the feedback.
Joe