Jail upgrades are part of your regular maintenance schedule to make sure the security patches are applied and you're running the latest release. Jails are a great tool for hosting additional workloads on your NAS. Jails provide lightweight isolation of your applications, such as Plex & Home Assistant.

List jails

List the available jails using the list command. This will show the name of the jail, its running state and importantly which release it is based on. From my example below I can see the zwavejs jail is running an older release than the other jails.

iocage list

# sudo iocage list
+-----+--------------+-------+--------------+--------------+
| JID |     NAME     | STATE |   RELEASE    |     IP4      |
+=====+==============+=======+==============+==============+
| 10  | adguard      | up    | 12.3-RELEASE | 10.0.0.5/24  |
+-----+--------------+-------+--------------+--------------+
| 8   | home         | up    | 12.3-RELEASE | 10.0.0.20/24 |
+-----+--------------+-------+--------------+--------------+
| 2   | plex         | up    | 12.3-RELEASE | 10.0.0.21/24 |
+-----+--------------+-------+--------------+--------------+
| 1   | zwavejs      | up    | 12.2-RELEASE | 10.0.0.25/24 |
+-----+--------------+-------+--------------+--------------+

Jail update

An update will pull in all the latest patches for the current jail. Jails can be updated either in a stopped or running state.

iocage update [JAIL]

# sudo iocage update adguard
Snapshot: vol0/iocage/jails/adguard@ioc_update_12.3-RELEASE-p5_2022-05-05_10-12-15 created.
Updating jail...

* Updating 12.3-RELEASE to the latest patch level...
Looking up update.FreeBSD.org mirrors... 2 mirrors found.
Fetching metadata signature for 12.3-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Inspecting system... done.
Preparing to download files... done.

No updates needed to update system to 12.3-RELEASE-p5.
No updates are available to install.
Run '/tmp/tmptnjbba5j fetch' first.
release: 12.3-RELEASE-p5 -> 12.3-RELEASE-p5
release: 12.3-RELEASE-p5 -> 12.3-RELEASE-p5
Updated jail successfully.

adguard updates have been applied successfully.

Note

A snapshot is automatically created during a jail update

Jail upgrade

To upgrade your jail, use the upgrade command. An upgrade will move the jail to a new release of FreeBSD.

Before you can upgrade a jail, you first need to fetch a new release that you will be upgrading to. This is done via the fetch command. From the interactive menu, choose the release you want to download to your system and make available for jail upgrades.

iocage fetch

# sudo iocage fetch
[0] 12.3-RELEASE
[1] 13.0-RELEASE

Type the number of the desired RELEASE
Press [Enter] to fetch the default selection: (12.2-RELEASE)
Type EXIT to quit:

Once the new release has been fetched (this can take up to 10 minutes to download and decompress and patch), the next step is to upgrade existing jails to use the new release. The is done by specifying the release along with the target jail.

iocage upgrade -r [RELEASE] [JAIL]

# sudo iocage upgrade -r 12.3-RELEASE zwavejs

zwavejs successfully upgraded from 12.2-RELEASE-p15 to 12.3-RELEASE-p5!
Please reboot the jail and inspect.
Remove the snapshot: ioc_upgrade_2022-05-04 if everything is OK

Note

A snapshot is automatically created during a jail upgrade

Restarting jails

The last step in either a jail update or upgrade is to restart the jail itself. Without a restart, the running services will continue to execute in their pre-upgrade state.

iocage restart [JAIL]

# sudo iocage restart adguard
* Stopping adguard
  + Executing prestop OK
  + Stopping services OK
  + Tearing down VNET OK
  + Removing devfs_ruleset: 1005 OK
  + Removing jail process OK
  + Executing poststop OK
* Starting adguard
  + Started OK
  + Using devfs_ruleset: 1005 (iocage generated default)
  + Configuring VNET OK
  + Using IP options: vnet
  + Starting services OK
  + Executing poststart OK

Updating / upgrading all jails

If you have more than one jail, then updating and upgrading each individually can be a bit time consuming. Fortunately, iocage has built in support for updating and upgrading all the jails. Simply replace the jail name with ALL.

The ALL keyword only applies to basejails, so if you are using different jail types, you will probably want to iterate over the different jails to perform the update.

iocage update ALL

iocage upgrade -r [RELEASE] ALL

iocage restart ALL

Putting it all together

Update jails to latest patches:

iocage update ALL

Fetch your new release:

iocage fetch

Upgrade jails to the latest release:

iocage upgrade -r [RELEASE] ALL

Restart jails:

iocage restart ALL