Maintaining Jail Backups with Iocage

Managing jails in FreeBSD is easy, which is why I find them so appealing. So far everything I’ve written about jail management here has involved Bastille. For my home projects I like Bastille because its small and easy to use. For this webserver I use iocage, which I also use on TrueNAS at work. Iocage and Bastille appear to have pretty close feature parity, but I think iocage has a bit of an edge when it comes to integrating and managing ZFS snapshots and backups.

Snapshots are a nifty feature of ZFS that iocage takes advantage of to pretty much instantly save the state of your jail. You can also use ZFS to take snapshots of your entire system. This allows you to roll back to the snapshot should something disastrous happen. Keep in mind that snapshots are not backups. For backups, we’ll want to send our data to an external system or ideally systems. Snapshots are great to save you if something goes wrong internally with software. Backups, on the other hand, are necessary in case of hardware failure or something happens to the host.

I’m going to go over the basics of creating snapshots, recovering snapshots, and exporting backups using iocage. Note that these tasks can be automated using cron jobs, but to do so would probably require a script to only retain so many snapshots/backups (in the case of backups, this would probably be on a remote machine). For this article I’m just going to do things manually. Honestly, that’s how I do things for this site since I don’t update it enough to require a rigid backup schedule.

Iocage Snapshots

Creating snapshots in iocage is easy. Just use the command below and replace jailname with the name of your jail.

# iocage snapshot jailname
Snapshot: zroot/iocage/jails/testjail@2023-05-19_04:14:46 created.

You should see the success message, as above. If you don’t name your jail, it will be given a default name of the date and time it was taken. If you would like to add a name do the following, replacing snapshotname with your desired name:

# iocage snapshot -n snapshotname jailname

You can also look at all of your snapshots:

# iocage snaplist jailname

You’ll notice that the snapshots are much smaller than the actual jail. This is because they just record the changes that have occurred since the snapshot. Another great thing about snapshots is that they occur almost instant. I recommend making a snapshot before making any major changes to your jail, such as upgrading, updating software, or major configuration changes. Snapshots basically give you a be “undo” button in case something goes wrong.

How do you press that undo button? Iocage makes it easy:

# iocage rollback -n snapshotname jailname

Want to delete a snapshot? Again, it’s easy:

# iocage snapremove -n snapshotname jailname

Iocage Backups

Now let’s make a backup that iocage can restore later. In this case, I’m upgrading the host system from FreeBSD 13.1 to FreeBSD 13.2. That means I need to create the backup and transfer it to another system so if something goes catastrophically wrong during the upgrade process I have everything I need since I keep all vital applications jailed.

First, we have to stop the jail:

# iocage stop jailname

Now, let’s create the jail backup. Note that this process with create a compressed file containing your entire jail, so unlike the snapshot process this may take a while depending on the size of your jail and the speed of your server.

# iocage export jailname
Exporting dataset: zroot/iocage/jails/testjail
Exporting dataset: zroot/iocage/jails/testjail/root

Preparing compressed file: /zroot/iocage/images/testjail_2023-05-19.zip.

Exported: /zroot/iocage/images/testjail_2023-05-19.zip

You can see the file location above (/zroot/iocage/images/testjail_2023-05-19.zip).

For the next step, we need to move the jail to another machine. Since I’m just downloading it to my personal machine, I’m just going to use SFTP. If you’re sending it to a remote machine you could also use rsync or scp. Once you have your backup in a secure location, keep it there!

What to do if you need to restore from this backup? Iocage again makes it easy. Obviously, replace /path/to/backup with the path to your backup file.

# iocage import -p /path/to/backup jailname

Conclusion

Iocage makes it easy to take snapshots and backups and restore them. To automate this process, we can use a combination of cron jobs and a shell script. I think I know what my next article will be about.