ioc­age: HOWTO cre­ate a base­jail from src (in­stead of from an of­fi­cial re­lease)

Back­ground

So far I have used ez­jail to man­age FreeBSD jails. I use jails since years to have dif­fer­ent parts of a soft­ware stack in some kind of a con­tainer (in a ZFS data­set for the filesys­tem side of the con­tainer). On one hand to not let de­pend­en­cies of one part of the soft­ware stack have in­flu­ence of other parts of the soft­ware stack. On the other hand to have the pos­sib­il­ity to move parts of the soft­ware stack to a dif­fer­ent sys­tem if ne­ces­sary. Nor­mally I run -stable or –cur­rent or more gen­er­ally speak­ing, a self-​compiled FreeBSD on those sys­tems. In ez­jail I like the fact that all jails on a sys­tem have one com­mon base­jail un­der­ly­ing, so that I up­date one place for the user­land and all jails get the up­dated code.

Since a while I heard good things about ioc­age and how it in­teg­rates ZFS, so I de­cided to give it a try my­self. As ioc­age does not come with an of­fi­cial way of cre­at­ing a base­jail (re­spect­ively a re­lease) from a self-​compiled FreeBSD (at least doc­u­mented in those places I looked, and yes, I am aware that I can cre­ate a FreeBSD re­lease my­self and use it, but I do not like to have to cre­ate a re­lease ad­di­tion­ally to the build­world I use to up­date the host sys­tem) here now the short HOWTO achieve this.

In­vari­ants

In the fol­low­ing I as­sume the ioc­age ZFS parts are already cre­ated in data­set ${POOLNAME}/iocage which is moun­ted on ${IOCAGE_BASE}/iocage. Ad­di­tion­ally the build­world in /​usr/​src (or wherever you have the FreeBSD source) should be fin­ished.

Pre-​requisites

To have the ne­ces­sary dataset-​infrastructure cre­ated for own basejails/​releases, at least one of­fi­cial re­lease needs to be fetched be­fore. So run the com­mand be­low (if there is no ${IOCAGE_BASE}/iocage/releases dir­ect­ory) and fol­low the on-​screen in­struc­tions.

ioc­age fetch

HOWTO

Some vari­ables:

POOLNAME=mpool
SRC_REV=r$(cd /​usr/​src; svn­litever­sion)
IOCAGE_​BASE=””

Cre­at­ing the ioc­age basejail-​datasets for this ${SRC_​REV}:

zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/bin
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/boot
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/lib
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/libexec
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/rescue
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/sbin
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/bin
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/include
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/lib
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/lib32
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/libdata
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/libexec
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/sbin
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/share
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/base/${SRC_REV}-RELEASE/root/usr/src

In­stall from /​usr/​src (the ex­ecut­able “chown” is hard­linked across an ioc­age base­jail data­set bound­ary, this fails in the nor­mal in­stall­world, so we have to ig­nore this er­ror and in­stall a copy of the chown bin­ary to the place where the hard­link nor­mally is):

cd /​usr/​src
make –i in­stall­world DESTDIR=${IOCAGE_BASE}/iocage/base/${SRC_REV}-RELEASE/root >&! iocage_installworld_base.log
cp –pv ${IOCAGE_BASE}/iocage/base/${SRC_REV}-RELEASE/root/usr/sbin/chown ${IOCAGE_BASE}/iocage/base/${SRC_REV}-RELEASE/root/usr/bin/chgrp
make dis­tri­bu­tion DESTDIR=${IOCAGE_BASE}/iocage/base/${SRC_REV}-RELEASE/root »& iocage_installworld_base.log

While we are here, also cre­ate a re­lease and not only a base­jail:

zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/releases/${SRC_REV}-RELEASE
zfs cre­ate –o compression=lz4 ${POOLNAME}/iocage/releases/${SRC_REV}-RELEASE/root
make in­stall­world DESTDIR=${IOCAGE_BASE}/iocage/releases/${SRC_REV}-RELEASE/root >&! iocage_installworld_release.log
make dis­tri­bu­tion DESTDIR=${IOCAGE_BASE}/iocage/releases/${SRC_REV}-RELEASE/root »& iocage_installworld_release.log

And fi­nally make this the de­fault re­lease which ioc­age uses when cre­at­ing new jails (this is op­tional):

ioc­age set release=${SRC_REV}-RELEASE de­fault

Now the self-​build FreeBSD is avail­able in ioc­age for new jails.

Sock­ets and nullfs: works now in –cur­rent

I just up­dated to a re­cent -cur­rent and tried the new nullfs. Sock­ets (e.g. the MySQL one) work now with nullfs. No need to have e.g. jails on the same FS and hard­link the socket to not need to use TCP in MySQL (or an IP at all for the jail).

Great work!

X11 in a jail with NVidia hard­ware

Just be­fore christ­mas I de­cided I will spend the “im­mense” amount of 40 EUR for a graphic card for a sys­tem which was without one. The sys­tem is sup­posed to re­place my dy­ing home-​server. I already moved everything, ex­cept my Desktop-​in-​a-​Jail (ac­tu­ally it is my home-​cinema-​jail).

The old sys­tem had a Radeon 9200SE, and it was enough for what I used it for. Now… for a few bucks you can get a lot more horsepower today. Af­ter look­ing around a little bit I de­cided to buy a NVidia card. I made this de­cision be­cause it looks like I can get bet­ter driver sup­port for it. So I got a Ge­Force GT 520 with 1 GB of RAM (I doubt I will be able to use that much RAM) and without a fan.

With the Radeon 9200SE I was not able to get the 3D stuff ac­tiv­ated (at least in the jail, I did not try without), Xorg com­plains about a miss­ing ag­p­gart mod­ule but I have AGP in the ker­nel (no /​dev/​agpgart out­side the jail). I did not spend time to in­vest­ig­ate this, as the main pur­pose – play­ing movies – worked. Now with the NVidia card I de­cided to give the 3D part a try again.

Af­ter adding the NVidia device entries to the jail, and a little bit of fight­ing with the Xorg-​HAL in­ter­ac­tion, I got a work­ing desktop. The biggest prob­lem to verify that 3D is work­ing was, that I did not had xdri­info in­stalled. Af­ter in­stalling it, I no­ticed that it does not work with the NVidia driver.  🙁  Next stop nvidia-​settings: runs great, dis­plays a nice FreeBSD+NVidia logo, and … tells me that OpenGL is con­figured. Hmmm… OK, but I want to see it!

As I de­cided to switch from Gnome to KDE 4 at  the same time (I was us­ing KDE when it was at V 0.x, switched to Gnome as it looked nicer to me, and now I switch back af­ter read­ing all the stuff in the net that KDE 4 is “bet­ter” than Gnome 3), I was a little bit out of know­ledge how to see the 3D stuff in ac­tion. So I quickly went to the set­tings and searched for some­thing which looks like it may use 3D. To my sur­prise, it was already us­ing 3D stuff. Nice. I fully real­ized how nice, when play­ing a video and us­ing Alt-​Tab to switch win­dows: the video was play­ing full speed scaled down in the window-​switcher-​thumbnail-​view.

That was too easy. I am happy about it.

Now that I have a work­ing setup of X11-​in-​a-​jail for Radeon and Ge­Force cards, I want to cleanup my changes to the ker­nel and the con­fig files (devfs.rules) and have a look to get this com­mit­ted. A big part of this work is prob­ably writ­ing doc­u­ment­a­tion (most prob­ably in the wiki).

I still want to see some fancy 3D stuff now. I tried to in­stall x11-​clocks/​glclock, but the build fails with an un­defined ref­er­ence to ‘glPoly­gonOff­se­tEXT’. 🙁 Any re­com­mend­a­tion for a fancy 3D dis­play? My pri­or­ity is on “fancy/​nice” with as less vi­ol­ence as pos­sible. Most prob­ably I will look at it once and then dein­stall it again, so it should be avail­able in the Ports Col­lec­tion (or in­cluded in KDE 4).

How I setup a Jail-​Host

Every­one has his own way of set­ting up a ma­chine to serve as a host of mul­tiple jails. Here is my way, YMMV.

Ini­tial FreeBSD in­stall

I use sev­eral hard­disks in a Soft­ware–RAID setup. It does not mat­ter much if you set them up with one big par­ti­tion or with sev­eral par­ti­tions, feel free to fol­low your pref­er­ences here. My way of par­ti­tion­ing the hard­disks is de­scribed in a pre­vi­ous post. That post only shows the com­mands to split the hard­disks into two par­ti­tions and use ZFS for the rootfs. The com­mands to ini­tial­ize the ZFS data par­ti­tion are not de­scribed, but you should be able to fig­ure it out your­self (and you can de­cide on your own what kind of RAID level you want to use). For this FS I set atime, exec and setuid to off in the ZFS op­tions.

On the ZFS data par­ti­tion I cre­ate a new data­set for the sys­tem. For this data­set I set atime, exec and setuid to off in the ZFS op­tions. In­side this data­set I cre­ate data­sets for /​home, /​usr/​compat, /​usr/​local, /​usr/​obj, /​usr/​ports/​, /​usr/​src, /​usr/​sup and /​var/​ports. There are two ways of do­ing this. One way is to set the ZFS moun­t­point. The way I prefer is to set re­l­at­ive sym­links to it, e.g. “cd /​usr; ln –s ../​data/​system/​usr_​obj obj”. I do this be­cause this way I can tem­por­ary im­port the pool on an­other ma­chine (e.g. my desktop, if the need arises) without fear to in­ter­fere with the sys­tem. The ZFS op­tions are set as fol­lows:

ZFS op­tions for data/​system/​*

Data­set

Op­tion

Value
data/​system/​home exec on
data/​system/​usr_​compat exec on
data/​system/​usr_​compat setuid on
data/​system/​usr_​local exec on
data/​system/​usr_​local setuid on
data/​system/​usr_​obj exec on
data/​system/​usr_​ports exec on
data/​system/​usr_​ports setuid on
data/​system/​usr_​src exec on
data/​system/​usr_​sup sec­ond­arycache none
data/​system/​var_​ports exec on

The exec op­tion for home is not ne­ces­sary if you keep sep­ar­ate data­sets for each user. Nor­mally I keep sep­ar­ate data­sets for home dir­ect­or­ies, but Jail-​Hosts should not have users (ex­cept the ad­mins, but they should not keep data in their homes), so I just cre­ate a single home data­set. The setuid op­tion for the usr_​ports should not be ne­ces­sary if you re­dir­ect the build dir­ect­ory of the ports to a dif­fer­ent place (WRKDIRPREFIX in /etc/make.conf).

In­stalling ports

The ports I in­stall by de­fault are net/​rsync, ports-​mgmt/​portaudit, ports-​mgmt/​portmaster, shells/​zsh, sysutils/​bsdstats, sysutils/​ezjail, sysutils/​smartmontools and sysutils/​tmux.

Ba­sic setup

In the crontab of root I setup a job to do a portsnap up­date once a day (I pick a ran­dom num­ber between 0 and 59 for the minute, but keep a fixed hour). I also have http_​proxy spe­cified in /​etc/​profile, so that all ma­chines in this net­work do not down­load everything from far away again and again, but can get the data from the local cach­ing proxy. As a little watch­dog I have a little @reboot rule in the crontab, which no­ti­fies me when a ma­chine re­boots:

@reboot grep “ker­nel boot file is” /​var/​log/​messages | mail –s “„host­name„ re­booted” root >/​dev/​null 2>&1

This does not re­place a real mon­it­or­ing solu­tion, but in cases where real mon­it­or­ing is overkill it provides a nice HEADS-​UP (and shows you dir­ectly which ker­nel is loaded in case a non-​default one is used).

Some de­fault ali­ases I use every­where are:

alias portmlist=“portmaster –L | egrep –B1 „(ew|ort) version|Aborting|installed|dependencies|IGNORE|marked|Reason:|MOVED|deleted|exist|update“ | grep –v „^ – “”
alias portmclean=“portmaster –t –clean-​distfiles –clean-​packages“
alias portmcheck=“portmaster –y –check-​depends”

Ad­di­tional devfs rules for Jails

I have the need to give ac­cess to some spe­cific devices in some jails. For this I need to setup a cus­tom /etc/devfs.rules file. The files con­tains some ID num­bers which need to be unique in the sys­tem. On a 9-​current sys­tem the num­bers one to four are already used (see /etc/defaults/devfs.rules). The next avail­able num­ber is ob­vi­ously five then. First I present my devfs.rules entries, then I ex­plain them:

[devfsrules_unhide_audio=5]
add path „au­dio*“ un­hide
add path „dsp*“ un­hide
add path midistat un­hide
add path „mixer*“ un­hide
add path „mu­sic*“ un­hide
add path „se­quen­cer*“ un­hide
add path snd­stat un­hide
add path speaker un­hide

[devfsrules_unhide_printers=6]
add path „lpt*“ un­hide
add path „ulpt*“ un­hide user 193 group 193
add path „un­lpt*“ un­hide user 193 group 193

[devfsrules_unhide_zfs=7]
add path zfs un­hide

[devfsrules_jail_printserver=8]
add in­clude $devfsrules_​hide_​all
add in­clude $devfsrules_​unhide_​basic
add in­clude $devfsrules_​unhide_​login
add in­clude $devfsrules_​unhide_​printers
add in­clude $devfsrules_​unhide_​zfs

[devfsrules_jail_withzfs=9]
add in­clude $devfsrules_​hide_​all
add in­clude $devfsrules_​unhide_​basic
add in­clude $devfsrules_​unhide_​login
add in­clude $devfsrules_​unhide_​zfs

The devfs_​rules_​unhide_​XXX ones give ac­cess to spe­cific devices, e.g. all the sound re­lated devices or to local print­ers. The devfsrules_​jail_​XXX ones com­bine all the un­hide rules for spe­cific jail setups. Un­for­tu­nately the in­clude dir­ect­ive is not re­curs­ive, so that we can not in­clude the de­fault devfsrules_​jail pro­file and need to rep­lic­ate its con­tents. The first three in­cludes of each devfsrules_​jail_​XXX ac­com­plish this. The unhide_​zfs rule gives ac­cess to /​dev/​zfs, which is needed if you at­tach one or more ZFS data­sets to a jail. I will ex­plain how to use those pro­files with ez­jail in a follow-​up post.

Jails setup

I use ez­jail to man­age jails, it is more com­fort­able than do­ing it by hand while at the same time al­lows me to do some­thing by hand. My jails nor­mally reside in­side ZFS data­sets, for this reason I have setup a spe­cial area (ZFS data­set data/​jails) which is handled by ezjail.The cor­res­pond­ing ezjail.conf set­tings are:

ezjail_jaildir=/data/jails
ezjail_use_zfs=“YES“
ezjail_jailzfs=“data/jails”

I also dis­abled procfs and fdescfs in jails (but they can be en­abled later for spe­cific jails if ne­ces­sary).

Un­for­tu­nately ez­jail (as of v3.1) sets the moun­t­point of a newly cre­ated data­set even if it is not ne­ces­sary. For this reason I al­ways is­sue a “zfs in­herit moun­t­point ” af­ter cre­at­ing a jail. This sim­pli­fies the case where you want to move/​rename a data­set and want to have the moun­t­point autom­c­at­ic­ally fol­low the change.

The ac­cess flags of  /​data/​jails dir­ect­ory are 700, this pre­vents local users (there should be none, but bet­ter safe than sorry) to get ac­cess to files from users in jails with the same UID.

Af­ter the first create/​update of the ez­jail base­jail the ZFS op­tions of base­jail (data/​jails/​basejail) and new­jail (data/​jails/​newjail) need to be changed. For both exec and setuid should be changed to “on” The same needs to be done af­ter cre­at­ing a new jail for the new jail (be­fore start­ing it).

The de­fault ez­jail fla­vour

In my de­fault ez­jail fla­vour I cre­ate some de­fault user(s) with a basesystem-​shell (via /data/jails/flavours/mydef/ezjail.flavour) be­fore the pack­age in­stall, and change the shell to my pre­ferred zsh af­ter­wards (this is only valid if the jails are used only by in-​house people, if you want to of­fer light­weight vir­tual ma­chines to (un­known) cus­tom­ers, the de­fault user(s) and shell(s) are ob­vi­ously up to dis­cus­sion). At the end I also run a “/​usr/​local/​sbin/​portmaster –y –check-​depends” to make sure everything is in a sane state.

For the pack­ages (/​data/​jails/​flavours/​mydef/​pkg/​) I add sym­links to the un­ver­sioned pack­ages I want to in­stall. I have the pack­ages in a com­mon (think about set­ting PACKAGES in make.conf and us­ing PACKAGES/Latest/XYZ.tbz) dir­ect­ory (if they can be shared over vari­ous fla­vours), and they are un­ver­sioned so that I do not have to up­date the ver­sion num­ber each time there is an up­date. The pack­ages I in­stall by de­fault are bsdstats, portaudit, port­mas­ter, zsh, tmux and all their de­pend­en­cies.

In case you use jails to vir­tu­al­ize ser­vices and con­sol­id­ate servers (e.g. DNS, HTTP, MySQL each in a sep­ar­ate jail) in­stead of provid­ing light­weight vir­tual ma­chines to (un­known) cus­tom­ers, there is also a be­ne­fit of shar­ing the dist­files and pack­ages between jails on the same ma­chine. To do this I cre­ate /data/jails/flavours/mydef/shared/ports/{distfiles,packages} which are then moun­ted via nullfs or NFS into all the jails from a com­mon dir­ect­ory. This re­quires the fol­low­ing vari­ables in /data/jails/flavours/mydef/etc/make.conf (I also keep the pack­ages for dif­fer­ent CPU types and com­pilers in the same sub­tree, if you do not care, just re­move the “/${CC}/${CPUTYPE}” from the PACAKGES line):

DISTDIR=  /​shared/​ports/​distfiles
PACKAGES= /shared/ports/packages/${CC}/${CPUTYPE}

New jails

A fu­ture post will cover how I setup new jails in such a setup and how I cus­tom­ize the start or­der of jails or use some non-​default set­tings for the jail-​startup.

All in­ternal ser­vices mi­grated to IPv6

In the last days I mi­grated all my in­ternal ser­vices to IPv6.

All my jails have an IPv4 and an IPv6 ad­dress now. All Apaches (I have one for my pic­ture gal­lery, one for web­mail, and one for in­ternal man­age­ment) now listen on the in­ternal IPv6 ad­dress too. Squid is up­dated from 2.x to 3.1 (the most re­cent ver­sion in the Ports Col­lec­tion) and I ad­ded some IPv6 ACLs. The in­ternal Post­fix is con­figured to handle IPv6 too (it is de­liv­er­ing everything via an au­then­tic­ated and en­cryp­ted chan­nel to a ma­chine with a static IPv4 ad­dress for fi­nal de­liv­ery). My MySQL does not need an IPv6 ad­dress, as it is only listen­ing to re­quests via IPC (the socket is hard­linked between jails). All ssh dae­mons are con­figured to listen to IPv6 too. The IMAP and CUPS server was pick­ing the new IPv6 ad­dresses auto­mat­ic­ally. I also up­dated Samba to handle IPv6, but due to lack of a Win­dows ma­chine which prefers IPv6 over IPv4 for CIFS ac­cess (at least I think my Win­dows XP net­book only tries IPv4 con­nec­tions) I can not really test this.

Only my Wii is a little bit be­hind, and I have not checked if my Sony-​TV will DTRT (but for this I first have to get some time to have a look if I have to up­date my DD-​WRT firm­ware on the little WLAN-​router which is “ex­tend­ing the cable” from the TV to the in­ternal net­work, and I have to look how to con­fig­ure IPv6 with DD-​WRT).