Migrating a jail

Thick iocage jails can be safely migrated between FreeBSD hosts using ZFS Send/Recv over SSH.

In the following example:

src$ is the original host
dst$ is the destination host
‘myapp’ is the name of my jail to migrate
Everything is done with root privileges

Stopping processes

Stop the jail and any other ZFS replication processes.

src$ iocage stop myapp

src$ service zrepl stop

dst$ service zrepl stop

Create a snapshot

src$ zfs snapshot -r zroot/iocage/jails/myapp@migration

Send the snapshot

src$ zfs send -R zroot/iocage/jails/myapp@migration | ssh root@dst 'zfs recv -F -v zroot/iocage/jails/myapp'

Testing

Check that the jail exists and that it can be started.

dst$ iocage list

dst$ iocage start myapp

I have been using iocage for a number of years as the tool to manage my FreeBSD jails. There are two types of iocage jail installations that I use, thin jails (clone jails) and thick jails.

To create your first jail, you have to fetch a FreeBSD operating system release installation using ‘iocage fetch’. This is used in both types of jails and is separate from the host’s own operating system.

Thin jails share the ZFS dataset that contains the working copy of a fetched version of FreeBSD. They save a lot of space as upgrading FreeBSD one thin jail, upgrades them all.

Thick jails have their own independent copy of the chosen fetched FreeBSD. They use more disk space and take more time to upgrade as each must be done individually.

The extra time and disk space used by Thick jails are worth it. Moving jails between hosts, performing backups and restores using ZFS Send and Receive are a significant advantage.

The requirement

I needed to migrate a thin jail from one host to another but at the destination I wanted it to run as a thick jail instead. As I have found that thick jails are better for me when it comes to upgrades. The migration of a thin jail cannot be done using ZFS Send/Recv as is.

How to do it

Create a new thick jail using iocage called ‘thickjail’.

$ iocage create -T -r 14.3-RELEASE -n thickjail dhcp=on

Check that the new thick jail works by starting and stopping it.

$ iocage start thickjail

$ iocage stop thickjail

$ iocage stop myapp

Copy the files from the thin jail to the thick jail using rsync. Make sure both jails have been stopped beforehand!

$ rsync -a /zroot/iocage/jails/myapp/ /zroot/iocage/jails/thickjail/

When this completes you will notice two jails with the same name when you use ‘iocage list’. However, if you look at the ZFS datasets they will be correctly named.

To correct the listing in iocage, do the the following:

$ iocage rename myapp thinjail

$ iocage rename thickjail myapp

$ iocage start myapp

Test that the new thick jail ‘mayapp’ is working OK before deleting the old thin jail.

$ iocage list

$ iocage destroy thinjail