≡ Menu

How To Upgrade FreeBSD Jail ( OS Level Virtualization )

Q. I've FreeBSD jail configured as explained in man pages using make world options. Now I've upgrade my base FreeBSD 7.0 system to FreeBSD 7 patch level 4. How do I upgrade my Jail (FreeBSD VPS) so that everything get updated inside jail?

A. The FreeBSD jail mechanism is an implementation of operating system-level virtualization that allows administrators to partition a FreeBSD-based computer system into several independent mini-systems called jails. FreeBSD jails offer security, ease of delegation and os level virtualization. To upgrade your jail using make world use the following commands.

Step # 1: Build world

Follow this guide to upgrade your running system. Once done type the following command to build world for jail:

WARNING! There are various ways of creating and upgrading jails. This method uses make world upgrade method as original jail was created using make build itself.

# JAIL=/path/to/jail
# JAIL=/usr/home/jail/
# cd /usr/src
# make buildworld DESTDIR=$JAIL

Please note that If you have just done make buildworld previously you can do make installworld and save the time.

Step # 2: Stop jail service

Type the following command to stop all jails:
# /etc/rc.d/jail stop

Step # 3: Upgrade jail

Type the following command to stop all jails:
# cd /usr/src
# make installworld DESTDIR=$JAIL
# mergemaster -i -C -D $JAIL

If you have multiple jail repeat above steps. You can also try something as follows:
# JPATHS="/jail/path1 /jail/path2 /jail/path3"
# for j in $JPATHS; make installworld DESTDIR=$j; done

Step # 4: Start all jails

Type the following command:
# /etc/rc.d/jail start
Make sure everything is running:
# jls
Try to connect to jail called www.example.com with 20 as jail id from host itself:
# jexec 20 sh
# hostname
# sockstat

Try to upgrade FreeBSD ports inside jail:
# portsnap fetch update
# portversion -l '<' # portupgrade -a

Exit from jail and go back to host:
# exit

Further readings

Tweet itFacebook itGoogle+ itPDF itFound an error/typo on this page?

{ 11 comments… add one }

  • Valqk September 12, 2008, 9:45 am

    You can optionally use ezjail – /usr/ports/sysutils/ezjail
    A *great* tool, you can automatically create new jail for seconds, there are ‘flavours’ that you can configure and have *almost anything* setuped in new jail upon creation.
    Also you can create jail in regular image file (which can be crypted!)… a lot of features and one of the best – upgrade in 3 steps:
    1. cvsup /usr/src dir.
    2. build/install world on base system.
    2. ezjail-admin update -i
    If the -i (install only) option is given, ezjail-admin update only per-
    formes a make installworld, otherwise make world is invoked.

  • Chris Ruiz September 13, 2008, 9:19 pm

    You missed a very important step- you must run mergemaster to update /etc in the new jail!

    after running make installworld DESTDIR=$JAIL you need to run mergemaster -i -C -D $JAIL

  • nixCraft September 14, 2008, 5:50 pm


    Thanks for the heads up.

    Thanks for sharing your idea.

  • demerzel September 16, 2008, 6:10 pm

    thanks for this mini howto :)
    just a question… you say:
    make buildworld DESTDIR=$JAIL

    is really necessary setting DESTDIR variable while
    making buildworld?

    you also say:
    “Please note that If you have just done make buildworld previously you can do make installworld and save the time.”

    This makes me think… one buildworld… one or more installworld (with different DESTDIR for each jail)

    either DESTDIR in buildworld is useless or we have
    to make buildworld for each jail…

    Just to be sure,
    thank you very much indeed ;)

  • nixCraft September 16, 2008, 6:40 pm

    is really necessary setting DESTDIR variable while making buildworld?
    No, you can actually run it as follows:
    make buildworld
    make installworld DESTDIR=/path/to/jail/1
    make installworld DESTDIR=/path/to/jail/2
    make installworld DESTDIR=/path/to/jail/N


  • David October 28, 2008, 7:26 pm

    For “Step # 4: Start all jails”, you have:

    # /etc/init.d/jail start

    It should be:

    # /etc/rc.d/jail start

  • nixCraft October 29, 2008, 3:19 am


    Thanks for the heads up.

  • Sigmar Wiesmayr November 11, 2008, 4:29 pm

    Hi folks, I’m asking myself, whether it will be safe to do this upgrade from 6.3-RELEASE to 7.0-RELEASE.

    Anybody out there, how has done a major version upgrade with his base system and then with his jails?

    What will the jails do when hosted by a 7.0-RELEASE but themselves not upgraded yet?


  • Andrew January 10, 2009, 4:22 am

    I haven’t done a major upgrade (6.3-to-7.0) of a jail host system jet, but I’ve successfully upgraded a production server from a minor release to another (RELENG_6_2 to RELENG_6_3), by using the method described by Valqk (ezjail-admin update + mergemaster), and all worked fine!

  • Lars October 8, 2009, 9:49 am

    I’ve upgraded jails from FreeBSD 6.3 to 7.0-REL and it worked like a charm.

  • Leo Vandewoestijne October 24, 2011, 2:27 pm

    Minor detail; in stead of
    portversion -l ‘<'
    I prefer
    portversion -L =
    as that would display more potential trouble -in case there is any-.

Leave a Comment