• Home
  • Blog
  • Updating iocage jails in FreeNAS

Updating iocage jails in FreeNAS

Vincent Danen

February 17, 2020

I've been running FreeNAS as a file and application server for quite a while and love it. The FreeBSD jails are awesome for running applications like Plex or gitea in isolation. Recently the base FreeBSD 11.2-RELEASE went end of life and 11.3-RELEASE was the new stable version (actually, it went EOL last October but I only realized it the other day). Updates for packages can still be done within the jails, but upgrading the base jail can't be done from within the jail itself.

Instructions are around on how to do it, however I like blogging things that I know I'll be coming back to and "consumer 1" for this blog is me. If you're looking for a quick tutorial on how to upgrade the base jail on FreeNAS, then this may be of use to you. Undoubtably it will be useful to future me.

Unfortunately, as of the current FreeNAS 11.3-RELEASE this cannot be done in the GUI, so we need to resort to the shell. Open a console or ssh into your FreeNAS server, to an account with sudo privileges, and get a list of jails:

$ sudo iocage list
| JID |    NAME     | STATE |   RELEASE    | IP4  |
| 2   | gitea       | up    | 11.2-RELEASE | DHCP |
| 3   | inkdrop     | up    | 11.3-RELEASE | DHCP |
| -   | openproject | down  | 11.2-RELEASE | DHCP |
| 1   | plex        | up    | 11.2-RELEASE | DHCP |

On my system. the plex, gitea, and openproject jails were created quite some time ago and are running the 11.2-RELEASE version of FreeBSD. The inkdrop jail was created recently using the 11.3-RELEASE template. We'll upgrade the openproject jail first since that one means less to me than plex or gitea.

The first step is to make sure it is at the latest patch release:

$ sudo iocage update openproject
Snapshot: storage/iocage/jails/openproject@ioc_update_11.2-RELEASE-p15_2020-02-16_08-14-35 created.
Updating jail...

* Updating openproject to the latest patch level...
src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching metadata signature for 11.2-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Inspecting system... done.
Preparing to download files... done.

No updates needed to update system to 11.2-RELEASE-p15.

Any security issues discovered after Wed Oct 30 18:00:00 MDT 2019
will not have been corrected.
src component not installed, skipped
No updates are available to install.
Run '/tmp/tmpqduc4ubh fetch' first.

When I did this first, update it looked like it created a snapshot. I don't know if this is a feature or not (or I did something by accident?), but either way it's a good idea to make sure you have a current snapshot. You can examine whether or not that is the case:

$ sudo iocage snaplist openproject
|                         NAME                         |        CREATED        | RSIZE | USED  |
| ioc_update_11.2-RELEASE-p4                           | Sat Feb 15 10:23 2020 | 184K  | 120K  |
| ioc_update_11.2-RELEASE-p4/root                      | Sat Feb 15 10:23 2020 | 2.61G | 11.5M |
| ioc_update_11.2-RELEASE-p15_2020-02-16_08-14-35      | Sun Feb 16  8:14 2020 | 192K  | 120K  |
| ioc_update_11.2-RELEASE-p15_2020-02-16_08-14-35/root | Sun Feb 16  8:14 2020 | 2.67G | 1.44M |

If you do see your snapshots are out of date, you can create one using sudo iocage snapshot openproject. It also appears that it creates a snapshot as part of the upgrade, but I personally wouldn't rely on the good will of computers and would create a snapshot anyways.

The snapshots look current so we'll go ahead and do the upgrade to the new version. This will take about 10 minutes and may interactively ask you to do things like merge or edit configuration files. I note this not because it asked me for any of the three systems I upgraded, but because I had read elsewhere that it could happen.

The output below is trimmed but you should get a sense of what to expect. You need to specify the version to upgrade to (11.3-RELEASE) and the jail name (openproject in this case). When you're asked about the the components that appear to be installed or not, and are asked whether it looks reasonable, answer y to continue (to be honest, I have no idea but it seemed reasonable enough to me!).

$ sudo iocage upgrade -r 11.3-RELEASE openproject
src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching metadata signature for 11.2-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata files... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
world/base world/doc world/lib32

The following components of FreeBSD do not seem to be installed:
world/base-dbg world/lib32-dbg

Does this look reasonable (y/n)? y

Fetching metadata signature for 11.3-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.
To install the downloaded upgrades, run "/tmp/tmp7yqr2bxf install".
src component not installed, skipped
Installing updates...
Kernel updates have been installed.  Please reboot and run
"/tmp/tmp7yqr2bxf install" again to finish installing updates.
src component not installed, skipped
Installing updates... done.

openproject successfully upgraded from 11.2-RELEASE-p15 to 11.3-RELEASE-p6!

When this is done, enter the jail using sudo iocage console openproject and run pkg update && pkg upgrade to upgrade all of the packages inside.

At this point you can use sudo iocage list to verify the release is as expected as well, or use the web UI to verify. That's pretty much all there is to it. Everything should work properly. I successfully did this with all three jails with a minimum of fuss.

April 13, 2020 @ 3:45 AM

Thank you for this write-up.

I have heard of many people updating their iocage jails from 11.2 to 11.3 prior to the 11.3 upgrade, but is there any problem with staying on 11.2-U8 while maintaining 11.3 jails? Might some kind of conflict arise down the road?

Vincent Danen
April 13, 2020 @ 3:33 PM

I don't think you have to update your jails before you do the upgrade. IIRC, I was already running 11.3 before I upgraded my jails. Note that the jails have an OS internally so it will complain about a kernel mismatch (the host kernel running 11.3 while you're running an 11.2 release in the jail/guest). But it should work fine... I think I had one jail running 11.3 while the host was running 11.3 and that was only because I created that jail after I had upgraded. The others ran fine.

May 17, 2020 @ 3:02 PM

Thanks for this very succinct explanation. I had the error

pkg: repository meta /var/db/pkg/FreeBSD.meta has wrong version 2

when I tried to run pkg update. After various attempts to force pkg to update I found the command I needed to get pkg to start again and grab the correct version was

pkg bootstrap -f

October 17, 2020 @ 3:22 PM

I actually consulted many forum/blog posts (including this one) to see about properly upgrading the FreeNAS (IOCAGE) jail version, and thought I'd add to the discussion with these comments / observations:

I have a single jail (for Plex) that was at the 11.2-RELEASE version. The IXSystems site recommended the jail versions to be kept at the same version as the IOCAGE host, and my FreeNAS installation has been at 11.3 for some time (U5 at the moment). At first, I tried issuing the "iocage upgrade" command using "FreeNAS-11.3-U5" as the 'version to upgrade to' (cut-and-paste it from the FreeNAS Dashboard), but as a caution to others, this will produce Python errors with a 404 Not Found result. As shown in this thread, the "FreeNAS-" prefix is alltogether omitted, and even the upgrade level (-U5) is left off. It appears that the version must be entered, followed by "-RELEASE" (MUST be UPPER-CASE!). So, that gives the 11.3-RELEASE value as shown in this post above. As part of the upgrade process, the most current update version will also be patched in (in my case, it is 11.3-RELEASE-p14).

Also, if you walk away and come back later to check on the upgrade process (it will take some time), you will have to use your space bar to scroll through the pending messages for a long time (many directories are echoed back to the console), if you ran this through the FreeNAS shell.

January 22, 2021 @ 2:29 AM

Thanks for this. It did the trick for my FreeNas jails. Thanks again.

Brandon Totel
April 15, 2021 @ 5:22 PM

This was very helpful but I stumbled across some other items you could add to your write up. As an example if you have not already downloaded the version you want to upgrade to you first need to Fetch the version using 'iocage fetch" which will then prompt you for the version you want to download for the upgrade process. Also if during the upgraded in the CLI you have the word 'End' as the last item in the CLI, hit the letter Q to jump to the end of the script. If you dont, hitting space bar does nothing unless you are at the semi-colon prompt.

Luis Rossi
February 25, 2022 @ 4:31 PM

In your post you are upgrading a jail used fro openproject. Do you happen to have another post explaining how to install openproject in a freenas/truenas jail?

I have wasted a couple of weeks trying to do this without success.

Any help or pointers would be appreciated. Thanks,

Vincent Danen
March 04, 2022 @ 11:03 PM

Hi Luis. I was going to play with openproject and just ran out of time and never ended up doing so. Sorry I can't provide any pointers.

Leave a Comment

Comments use MarkDown. Need help? MarkDown Cheatsheet