Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 15 Apr 2012 15:19:36 -0700
From:      Devin Teske <>
To:        Mark Felder <>
Subject:   Re: jail v2 documentation?
Message-ID:  <>
In-Reply-To: <op.wcrxfstz34t2sn@cr48.lan>
References:  <> <op.wcp7j6tl34t2sn@cr48.lan> <> <op.wcrxfstz34t2sn@cr48.lan>

Next in thread | Previous in thread | Raw E-Mail | Index | Archive | Help

On Apr 14, 2012, at 2:19 PM, Mark Felder wrote:

> On Sat, 14 Apr 2012 14:59:47 -0500, <> wrote:
>> I don't see any v2 in the jail environment. Vimage is a separate softwar=
e module that is not part of the the system base release. It has to be comp=
iled into a custom kernel to be enabled and it's labeled as experimental, "=
use at your own risk". Not some thing I would want in my jail environment. =
So the bottom line is there is no version 2 of the jail environment,(IE cha=
nges to the jail command and its associate commands).
> Actual changes to the jail command can be found here:
> How to use the jails v2 is covered many places. It does indeed exist, and=
 you can probably use the package here to get yourself started because the =
rc.d script for jails is not updated to handle v2 jails.

The ".shtml" that I added in the website re-design looks nicer ^_^

I'm also planning on updating it with nice and pretty netgraph drawings.

When you're using my vimage package, you can use the following command to p=
roduce a nice diagram of your network:

sudo ngctl dot | dot -Tsvg -o $HOSTNAME-vimages.svg

Requires graphics/graphviz from ports/packages.

NOTE: I personally like SVG as it scales very nicely. Five command-line dri=
ven X11 applications that can display SVG are graphics/gimmage, graphics/gt=
humb, graphics/gqview, graphics/gx, and graphics/eog. Also, the latest vers=
ion of every browser (including Firefox10/11, Chrome13, Safari5, and IE9) c=
an display SVG. Latent versions of Operating Systems have built-in support =
as well (including Mac OS X Lion and Windows 7).

Alternatively, you can generate PNG or JPG using one of:

sudo ngctl dot | dot -Tpng -o $HOSTNAME-vimages.png
sudo ngctl dot | dot -Tjpg -o $HOSTNAME-vimages.jpg

I've uploaded a PNG for viewing pleasure:

NOTE: If you really need JPG or PNG, graphics/ImageMagick has the "convert"=
 utility which is, well, almost magical in a sense (if not already hinted-a=
t by the name). ^_^

How to read the diagram:

The "pink" cluster at the top-right are "unused" interfaces. Unused in the =
sense that netgraph doesn't have anything to do with them. In my graph for =
our FreeBSD-8.1 server named "" (it runs jails, get i=
t? haha; and it's on the "jbsd" network, for jailed-bsd hosts).

In the diagram, "igb1" is shown as unused (it's displayed in the pink "disc=
onnected" cluster -- which, if you're viewing in the browser, mousing over =
the cluster will display "cluster_disconnected" as a reminder of its purpos=
e). This is not entirely true, it's in-use by the base-hose (warden0.jbsd).=
 The other unused item is the socket we used to dump the dot(1) graph (see =
ng_socket(4) and ngctl(8)).

In the SVG diagram, there are a total of 5 vimage jails running on the host=
, sharing one physical Ethernet port and one physical wire (flowing through=
 the igb0 interface). The five hosts are named (in rc.conf(5)):


All these hosts are using the same On-board Intel Gigabit (igb(4)) network =
interface as illustrated in the above linked-to SVG image.

An ether-link is created for each vimage and "hooked into" a bridge that is=
 created for the specific hardware interface. An upper-link is then created=
 between the bridge and the hardware interface. Finally (for convenience) a=
 lower-link is created between the bridge and the hardware interface (allow=
ing the base host -- warden0.jbsd -- to interact with the vimages).

The links and their types are rendered in octagons and the netgraph objects=
 are rendered as records (multi-field boxes). At the bottom-left of each re=
cord (the lower-left field) is the netgraph type. For example,

At the top-left of the graph you'll see a record where the top-field is "ng=
0_kps64a_dev:" (explained below), the lower-left field is "eiface", and the=
 lower-right field is "[15]:", the "eiface" is the netgraph type.

For each of the netgraph types, such as "eiface", "ether", "bridge", and "s=
ocket", you can say "man ng_{type}" (for exampe, "man ng_bridge" or "man ng=

The aforementioned top-field of each record is the interface name visible b=
y ifconfig(8) inside the vimage. The format is "ngNN_NAME" where "NN" is th=
e number starting at zero for each bridged interface (regardless of which u=
nderlying hardware interface is backing the netgraph(4)-created interface) =
and "NAME" is the rc.conf(5) name of the vimage.

Here's another SVG showing a machine running 7 high-security vimages:

We see something very different from this system. In this system, we're not=
 utilizing bridging versus simply shoving multiple network interfaces into =
various vimages. In this case, each vimage is given their own physical wire=
 and therefore the netgraph(4) system is never invoked as no bridging is pe=

Yet another SVG, this one displaying a more exotic setup with the base host=
 (named after a famous prison) housing vimages participating in multiple ne=
tworks with various routing et cetera=85

Our "unused" cluster shows (or doesn't for that matter) that the base host =
is using one interface and another [high security] vimage is using two inte=
rfaces (again, high security vimages that use whole interfaces aren't shown=
 in the netgraph(4) system, not by means of redaction but by means of no-br=
idging-necessary). Along side that there are another two vimages (named bee=
fcake and stats) that are bridged into igb0 (Intel Gigabit), and another 8 =
vimages bridged into igb1.

NOTE: Another thing that makes the high-security vimages more secure is tha=
t the base host (hosting the vimage) can't see the interface that is grante=
d to the vimage. However, this in no way is to imply that either netgraph(4=
) or bridging is insecure in any way. On the contrary, it is the particular=
 setup that is being advocated. A secure bridge can be created by removing =
the lower-link from the bridge and hardware interface. This is done with ng=
ctl(8) and can be hooked into the startup of like-minded vimages using exis=
ting rc.conf(5) constructs provided by vimage package version 1.0 or higher=
 -- current version is 1.4).

The information contained in this message is proprietary and/or confidentia=
l. If you are not the intended recipient, please: (i) delete the message an=
d all copies; (ii) do not disclose, distribute or use the message in any ma=
nner; and (iii) notify the sender immediately. In addition, please be aware=
 that any message addressed to our domain is subject to archiving and revie=
w by persons other than the intended recipient. Thank you.

Want to link to this message? Use this URL: <>