jaildk

Every jail consists of layers of directories mounted on top of each other using nullfs mounts. Some of them can be shared among jails, some are versioned.

Installation

Execute the following command:

./jaildk setup <directory>

This will create the directory structure required for the tool install the tool itself, create a template jail and build a base directory.

Basic usage

Let's say you installed jaildk into /jail and you want to create a new jail with the name 'myjail' and the ip address '172.16.1.1'.

The following steps need to be done:

Configure /etc/jail.conf

Create the file /etc/jail.conf with the following innitial contents:

* {
    exec.start = "/bin/sh /etc/rc";
    exec.stop = "/bin/sh /etc/rc.shutdown";
    allow.raw_sockets = "false";
    sysvmsg = "new";
    sysvsem = "new";
    sysvshm = "new";
    host.hostname = $name;
    path = "/jail/run/$name"; 
    exec.prestart = "/jail/bin/jaildk install $name start";
    exec.clean = "true";
}

myjail {
    ip4.addr = "172.16.1.1";
}

Refer to jail(8) for more possible settings.

Configure /etc/rc.conf

Next add the following lines to your /etc/rc.conf:

ifconfig_em0_alias0="inet 172.16.1.1/32"
jail_enable="YES"

You may need to replace the interface name em0 with the one in use on your system. To apply the alias to the interface you can use the netif rc script: /etc/rc.d/netif restart.

Create the jail

# jaildk create myjail

- cpdup -x /jail/log/.template-20201106 /jail/test/log/myjail-20201106
- cpdup -x /jail/home/.template/root-20201106 /jail/test/home/myjail/root-20201106
- cpdup -x /jail/etc/.template/etc-20201106 /jail/test/etc/myjail/etc-20201106
- cpdup -x /jail/etc/.template/local-etc-20201106 /jail/test/etc/myjail/local-etc-20201106
/jail/data/.template/www doesn't exist, ignored
/jail/data/.template/spool doesn't exist, ignored
- cp -pRp /jail/etc/.template/mount.conf /jail/test/etc/.template/ports.conf /jail/test/etc/.template/mtree.conf /jail/test/etc/myjail/
cp: /jail/etc/.template/ports.conf: No such file or directory
Creating /jail/etc/.template/jail.conf
Creating run and build dirs
- mkdir -p /jail/run/myjail
- mkdir -p /jail/build/myjail
DONE.
Consider adding the jail myjail to /etc/jail.conf!

To mount the build chroot of the new jail, execute:
jaildk build myjail

To login into the build chroot
jaildk blogin myjail

To mount the production chroot of the new jail, execute:
jaildk install myjail

To login into the build chroot
jaildk login myjail

To start the jail, execute:
jaildk start myjail

Mount the build chroot of the jail

# jaildk build myjail

Installing jail myjail
mount - mount -t nullfs -o rw /jail/base/12.1-RELEASE-p10 /jail/build/myjail
mount - mdmfs -o rw,nosuid,async -s 128m -p 1777 md /jail/build/myjail/tmp
mount - mount -t devfs dev /jail/build/myjail/dev
mount - mount -t nullfs -o rw /jail/log/myjail-20201106 /jail/build/myjail/var/log
mount - mount -t nullfs -o rw /jail/appl/default-20201106 /jail/build/myjail/usr/local
mount - mount -t nullfs -o rw /jail/etc/myjail/etc-20201106 /jail/build/myjail/etc
mount - mount -t nullfs -o rw /jail/etc/myjail/local-etc-20201106 /jail/build/myjail/usr/local/etc
mount - mount -t nullfs -o rw /jail/home/myjail/root-20201106 /jail/build/myjail/root

Chroot into the build dir and install software

jaildk blogin myjail
pkg install bash nginx curl ...
vi /usr/local/etc/rc.conf
vi /usr/local/etc/nginx/nginx.conf

Since the build chroot is writable you can install packages and configure everything as needed.

Using the ports collection

There might be cases when using pre build binary packages are not your thing. In such a case you want to use the FreeBSD Ports Collection.

jaildk supports this, here are the steps required:

Create a buildbase

A normal base directory cannot be used with the ports collection because jaildk removes libraries and binaries for security reasons from normal bases. To create a build base, execute:

jaildk base -b 12-RELEASE-build -w

Next, add the following entry to the configuration of you jail. To stay with our example, edit /jail/etc/myjail/jail.conf and add:

buildbase=12-RELEASE-build

Then install the build jail as usual:

jaildk build myjail

Install the current ports collection:

jaildk fetch

In case the ports version created does not match the version of your jail, you need to configure the different ports version in your jail config /jail/etc/myjail/jail.conf like this:

ports=20201127

Now you can enter the build jail and install ports the traditional way:

jaildk blogin myjail
cd /usr/ports/shells/bash
make config-recursive install clean

When done, install and start the jail

# jaildk install myjail 
Installing jail myjail
mount - mount -t nullfs -o ro /jail/base/12.1-RELEASE-p10 /jail/run/myjail
mount - mdmfs -o rw,nosuid,async -s 128m -p 1777 md /jail/run/myjail/tmp
mount - mount -t devfs dev /jail/run/myjail/dev
mount - mount -t nullfs -o rw /jail/log/myjail-20201106 /jail/run/myjail/var/log
mount - mount -t nullfs -o ro /jail/appl/default-20201106 /jail/run/myjail/usr/local
mount - mount -t nullfs -o ro /jail/etc/myjail/etc-20201106 /jail/run/myjail/etc
mount - mount -t nullfs -o ro /jail/etc/myjail/local-etc-20201106 /jail/run/myjail/usr/local/etc
mount - mount -t nullfs -o rw /jail/home/myjail/root-20201106 /jail/run/myjail/root

# jaildk start myjail
Jail myjail start:
Starting jails: myjail.

# jaildk startus myjail
Jail scipown status:
 JID             IP Address      Hostname                      Path
 myjail          172.16.1.1      myjail                        /jail/run/myjail
Jail myjail rc status:
syslogd is running as pid 28180.
cron is running as pid 52130.
php_fpm is running as pid 45558.
nginx is running as pid 63975.
===> fcgiwrap profile: mediawiki
fcgiwrap is running as pid 37682.

# jaildk jlogin myjail

You can use this to login into a database or execute commands inside the jail.

Updating a jail

The very first thing to do is to update the host system using freebsd-update.

Next create a new base version:

jaildk base -b `uname -r`

Now you can create clone of your jail with a new version:

jaildk clone -s myjail -d myjail -o 20201106 -n 20210422

Mount the build chroot for the new version:

jaildk build myjail start -b `uname -r` -v 20210422

And finally chroot into the new jail and update it:

jaildk blogin myjail
pkg update
...

The last step is to remove the current running jail, change the version in etc/myjail.conf, install and start the new version.

If there's anything wrong you can always go back to the previous version using the above steps.

Getting help

Although I'm happy to hear from jaildk users in private email, that's the best way for me to forget to do something.

In order to report a bug, unexpected behavior, feature requests or to submit a patch, please open an issue on github: https://github.com/TLINDEN/jaildk/issues.

Copyright and license

This software is licensed under the BSD license.

Authors

T.v.Dein

Project homepage

https://github.com/TLINDEN/jaildk

README.md

jaildk - a FreeBSD jail development kit