FreeNAS: Backup Jails Automatically Using IOCAGE Import and Export

FreeNAS: Backup Jails
A backup of your FreeNAS jails is important given the time and effort spend on setting up, customizing and configuring these jails. We can use IOCAGE to complete a backup of your jails. This article will show you how to simplistically export and backup your jails and also how to create a script which would automatically perform all the necessary steps for exporting and backing up your jail. We will setup an automatic cron job in the FreeNAS WebUI which can run on predefined schedule and at a time which is acceptable for the jails to be stopped, allowing you to set and forget you jail backup implementation. This article will also quickly show you how to migrate your jail between different ZFS pools and show you how to rename your pools. An export and rename is really nice if you want to not remove your jails from the ‘Plug-ins’ tab in the FreeNAS WebUI and if you want to have them called something more descriptive than ‘Plex’. So, lets get started.

This article is part of my series of FreeNas setup, configuration and install articles.

Manual Backup of a FreeNAS Jail

Start by logging into your FreeNAS WebUI and heading to the command line. You can of course use an SSH connection if your prefer. Enter the following command which will show you the names of your jails:


Stop the jail you would like to export,where [jailname] is the name of the jail you want to backup:
iocage stop [jailname]

Export the jail, where [jailname] is the name of the jail you want to backup:
iocage export [jailname]

The jail will export to /mnt/[pool]/iocage/images

You can copy it somewhere safe from there if you wish using the cp or mv command. There are two files you will need to copy a .zip files and a .sha256 file.

Restoring a Backup of a FreeNAS Jail

If something goes wrong with your jail and you need to restore it, you will have to restore the copy you’ve created (image file) back to the /mnt/[jailname]/iocage/images folder. Before you can do that, you first have to destroy the existing jail with the following commands:
iocage stop [jailname]
iocage destroy [jailname]

You will need to ensure that the image you wish to restore (the .zip and the .sha256 files) are in the /mnt/[pool]/iocage/images directory. Now you can run the following command to import the jail back:
iocage import [jailname]

Now you can start your jail again with the following command:
iocage start [jailname]

Creating a Script and Automating

We can set your jails to backup automatically by creating a script and then running it through a cron job. First lets create the script. Modify the example below to fit your system setup scenario. You will need to replace [jailname] with name of your jail and all the file locations with the appropriate location. You will see that the script export to a log file aswell and you will also need to make sure the log file location exists or remove the “>> /mnt/data/logs/Jail.log” from the end of the lines.

Example Script to Modify:


echo "---Starting Backup of FreeNAS Jails---" >> /mnt/data/logs/Jail.log
echo $(date) >> /mnt/ssd/logs/Jail.log

#Jail #1 Backup
echo "Backing Up Jail" >> /mnt/data/logs/Jail.log
echo $(date) >> /mnt/data/logs/Jail.log
iocage stop [jailname] >> /mnt/data/logs/Jail.log
iocage export [jailname] >> /mnt/data/logs/Jail.log
iocage start [jailname] >> /mnt/data/logs/Jail.log
echo "...Deleting old backups" >> /mnt/data/logs/Jail.log
echo $(date) >> /mnt/data/logs/Jail.log
rm /mnt/Backups/[jailname]* >> /mnt/data/logs/Jail.log
echo "...Moving current backup to stotage folders" >> /mnt/data/logs/Jail.log
echo $(date) >> /mnt/data/logs/Jail.log
mv -v /mnt/[jailname]/iocage/images/[jailname]* /mnt/Backups/[jailname] >> /mnt/data/logs/Jail.log

Now you can go to the FreeNAS WebUI and navigate to “Tasks -> Cron Jobs”. Click add a new task. Enter the description, and then in the command field enter the location of the script above that you’ve created. Now set a schedule for when you’d like it to run (I do it weekly) and make sure the task is enabled.

That’s it you have a task that backups your jails. You can test it out by clicking the three dots in the right hand column and selecting run. Be aware that this will stop your jail and depending on the size of your jail, it could be down for a while.

Migrating Jails to a Different Pool

First, you’ll need to stop the jails before they be exported:
iocage stop [jailname]

Like above, you will need to export your jail using the following command:
iocage export [jailname]

The jail will export to /mnt/[pool]/iocage/images. You can repeat for multiple jails should you wish.

The exported jail(s) should be moved to a safe place on a different pool. The following command basically resets iocage and will destroy all iocage data that has been created. Again make sure have backed-up your exported jails outside the iocage dataset before running this command:
iocage clean -a

Next we will need to reactivated iocage on it’s new pool. Use the following command creates the iocage dataset as well a sub-directories and child datasets in the new location:
iocage activate [poolname]

You can also pre-fetch any releases at this point as well using the following command. If you don’t do this now it will happen automatically next time you install a plugin or jail
iocage fetch 11.2-RELEASE

Finally copy the exported jails back into /mnt/[pool]/iocage/images, then restore them with the following commanad:
iocage import [jailname]

You will need to re-setup your mount points as they are probably pointing to the old locations.

You may also need to update some of the fstab locations if you’re migrating between machines and/or you have changed the location/pool of your jails. You can do this using the following command and update all of the locations to the new locations with the vi editor:

iocage fstab -e

Renaming a Jail

If you want to rename your jail, you can use the following command (once your jail is stopped):
iocage rename [jailname] [newjailname]

So that’s it! You can now backup, export, import migrate and rename your jails!

Happy FreeNASin’!


Updated: May 15, 2020

Migrating between Pools: (

Updating fstab information:

Liked it? Take a second to support digiMoot on Patreon!

6 thoughts on “FreeNAS: Backup Jails Automatically Using IOCAGE Import and Export

  1. This is great! Thank you.

    Nonetheless, I have two questions.

    1. I want to run this as a scheduled task, and it would make sense to not backup a jail that hasn’t changed since the last backup. So my script would have to test to see if a jail has changed since the last backup. Is there a way to do this?

    2. In addition to this script, which makes a local backup, I use the Duplicati plugin to backup components of my system off-site. Duplicati resides in its own jail and has its own scheduler to control when it does backups. Since the script has to stop each jail, I need to know if Duplicati is in the middle of a backup job and delay stopping its jail until the job is finished. What’s the best way to test if a program within a jail is running? (a script with ps & grep? — where would this have to be to run properly?)

  2. Hello

    Thank you for the useful information

    How and if is possible to modify the script to delete only 1 week old backups for example.

    Thank you

Leave a Reply

Your email address will not be published. Required fields are marked *