Skip to main content.

Tracking -STABLE and -CURRENT (FreeBSD)

2013-10-30

Live demo in BSD Now Episode 009 | Originally written by TJ for bsdnow.tv | Last updated: 2014/01/22

NOTE: the author/maintainer of the tutorial(s) is no longer with the show, so the information below may be outdated or incorrect.

In most of the BSDs, there are different branches (or "versions") of the OS that you can use. Often times in addition to the normal releases, there is a development version with the latest features. In FreeBSD, there are three main branches of the OS you can use: -RELEASE, -STABLE and -CURRENT. Each of them is aimed towards a different set of users and their needs. This tutorial will explain the differences between them and why you may or may not want to use a certain one. You'll also learn how to go from one to another, when possible. One of the advantages of doing a source upgrade (as is required for development branches) is that you can easily strip out parts of the OS that you don't want or need. We'll discuss that more as we go on. Let's start with a brief explanation of what each branch is and what it's mainly intended for.


-RELEASE

The -RELEASE branch is arguably the most stable branch of FreeBSD. That's exactly what it's designed to be, what the everyday end user installs and uses. When a -RELEASE is cut, the only updates it gets are either critical fixes or security flaws. Most users should use -RELEASE because its codebase is the most thoroughly tested. Binary upgrades between -RELEASE versions are also very fast and easy, using the freebsd-update tool. Keeping this branch up to date with the latest patches is very simple, especially since there are very few patches needed for it. Security fixes are announced on multiple mailing lists, so it's strongly recommended to subscribe to at least the main one.

Patching a -RELEASE branch for security fixes (on a supported version) is as easy as:

# freebsd-update fetch install

That's it! Signed binary patches will be downloaded and applied. The announcement email will tell you if you need to rebuild any ports (as is the case for some OpenSSL updates), restart any services or reboot (usually only needed for kernel updates). FreeBSD development moves fast, and there comes a time when you need to upgrade the OS to a whole new version if you want to keep getting security fixes. If you're running a -RELEASE, you can also use the freebsd-update tool for major upgrades. If you wanted to go from 9.1-RELEASE to 9.2-RELEASE, all you need to do is this:

# freebsd-update -r 9.2-RELEASE upgrade

All the needed files will be downloaded and put into place. You will be asked to merge some configuration files if needed. Two reboots will be required (one for kernel, one for userland), but freebsd-update will tell you everything you need to do. For more info, see this page.


-CURRENT

FreeBSD -CURRENT - sometimes called "HEAD" - is where all the new changes go first. It has all the new features, all the big updates, all the freshly-written code. This is the bleeding edge of the OS' development. It is sometimes highly experimental and/or unstable. Most of the time it's not - I've heard people say "FreeBSD -CURRENT is more stable than an Ubuntu release" - but I digress. If you're using -CURRENT, you are more or less expected to be able to fix your own problems, or provide helpful information so that the developers can find and fix whatever bug you've found. People who need or want the latest and greatest code should consider running this branch. While the security team doesn't officially support -CURRENT, all needed security fixes will be committed. If the security issue only affects -CURRENT, you'll have to watch the commit logs to find out about it. If you want to keep up with this branch, you should join these two mailing lists to see changes and any workarounds needed: freebsd-current and svn-src-head.

To go from -RELEASE or -STABLE to -CURRENT (note: you can't really go backwards easily) you'll need to checkout the latest SVN sources, then rebuild the kernel and userland. Let's remove your current sources if you have them, then install subversion from ports and go through the process.

# rm -rf /usr/src
# cd /usr/ports/devel/subversion
# make config-recursive install clean

There's also an "svnup" port in /usr/ports/net, and a subversion client in the base OS starting with FreeBSD 10. This is assuming you're running a version before 10, so we need to install it from the port as described above. Now we grab the source code from one of the mirrors.

# svn co https://svn0.us-west.freebsd.org/base/head /usr/src

For a list of SVN mirrors and their fingerprints, see: svn mirrors. You should verify the SSL fingerprint if you're using HTTPS. After the initial checkout (which may take some time), you can sync your sources with the latest by issuing the following command:

# svn update /usr/src

It's a good idea to read over /usr/src/Makefile the first time you do this, so you can better understand what make targets are and which ones to use. Another file you should regularly check before doing big upgrades is /usr/src/UPDATING. It documents needed workarounds for certain changes. After you've familiarized yourself with those two files, now might be a good time to remove any parts of the OS you're not interested in compiling or using. To do this, edit the /etc/src.conf file. Consult src.conf for a list of things you can remove, add or change. You can also customize the kernel, taking out things you don't want or adding things that aren't in GENERIC. For a brief explanation of custom kernels and how to configure one, see this page.

Next, we build the userland and kernel, then do the initial merge of configuration files in case there's anything needed for a successful upgrade.

# cd /usr/src
# make -j `sysctl -n hw.ncpu` buildworld
# make -j `sysctl -n hw.ncpu` buildkernel  ## Add "KERNCONF=yourkernelname" if you did a custom kernel.
# make installkernel                       ## Add "KERNCONF=yourkernelname" if you did a custom kernel.
# reboot                                   ## It's recommended to go to single user mode, but not required.
# cd /usr/src
# mergemaster -p                           ## If anything needs to be merged, added or removed.
# make installworld
# mergemaster -iUF                         ## You will merge the new config files with your old ones.
# yes | make delete-old
# yes | make delete-old-libs
# cd /usr/obj && chflags -R noschg * && rm -rf *
# reboot

Your system should now come back up as a -CURRENT installation! Remember to check the lists and files mentioned so far so you can stay up-to-date with the latest developments. If you went from one major version to another, for example 9.2-RELEASE to 10-CURRENT, you will need to rebuild all ports with portmaster or portupgrade. Systems running -CURRENT cannot be upgraded using the freebsd-update tool, you have to do source-based upgrades, recompiling the OS.


-STABLE

FreeBSD -STABLE is what the -RELEASE branch is made from. After new features have been tested for a while in -CURRENT, they're often merged into the -STABLE branch. Some big features stay in -CURRENT until a new major point release, but a lot of the improvements that would be beneficial to the next -RELEASE will be committed to -STABLE. Security fixes for -STABLE are announced on the regular mailing lists mentioned earlier, so you should really subscribe to it regardless of what branch you're running. New features in -STABLE become the next point release. For example, after 9.1 was released, all the new changes in -STABLE will eventually become 9.2. There's a process of BETA and RC (release candidate) tests before that happens. This branch should be considered a lot more mature and stable than -CURRENT, but there will be a few times when it may not build or work quite as expected. Problems are fixed very quickly, however. It's a good mix between "only security updates" and "new stuff every day." As recommended in the previous section, you should subscribe to a couple mailing lists to see important changes. freebsd-stable and svn-src-stable (for 9.X, replace if you're on a different major version).

If you don't already have subversion installed, let's install that and check out the source code.

# rm -rf /usr/src
# cd /usr/ports/devel/subversion
# make config-recursive install clean
# svn co https://svn0.us-west.freebsd.org/base/stable/9 /usr/src     ## Replace 9 with the branch you want.

For a list of SVN mirrors and their fingerprints, see: svn mirrors. You should verify the SSL fingerprint if you're using HTTPS. After the initial checkout (which may take some time), you can sync your sources with the latest by issuing the following command:

# svn update /usr/src

It's a good idea to read over /usr/src/Makefile the first time you do this, so you can better understand what make targets are and which ones to use. Another file you should regularly check before doing big upgrades is /usr/src/UPDATING. It documents needed workarounds for certain changes. After you've familiarized yourself with those two files, now might be a good time to remove any parts of the OS you're not interested in compiling or using. To do this, edit the /etc/src.conf file. Consult src.conf for a list of things you can remove, add or change. You can also customize the kernel, taking out things you don't want or adding things that aren't in GENERIC. For a brief explanation of custom kernels and how to configure one, see this page.

Next, we build the userland and kernel, then do the initial merge of configuration files in case there's anything needed for a successful upgrade.

# cd /usr/src
# make -j `sysctl -n hw.ncpu` buildworld
# make -j `sysctl -n hw.ncpu` buildkernel  ## Add "KERNCONF=yourkernelname" if you did a custom kernel.
# make installkernel                       ## Add "KERNCONF=yourkernelname" if you did a custom kernel.
# reboot                                   ## It's recommended to go to single user mode, but not required.
# cd /usr/src
# mergemaster -p                           ## If anything needs to be merged, added or removed.
# make installworld
# mergemaster -iUF                         ## You will merge the new config files with your old ones.
# yes | make delete-old
# yes | make delete-old-libs
# cd /usr/obj && chflags -R noschg * && rm -rf *
# reboot

Your system should now come back up as a -STABLE system! Remember to check the lists and files mentioned so far so you can stay up-to-date with the latest developments. If you went from one major version to another, for example 8.4-RELEASE to 9-STABLE, you will need to rebuild all ports with portmaster or portupgrade. Systems running -STABLE cannot be upgraded using the freebsd-update tool, you have to do source-based upgrades, recompiling the OS.

Latest News

New announcement

2017-05-25

Hi, Mr. Dexter. Also, we understand that Brad Davis thinks there should be more real news....

Two Year Anniversary

2015-08-08

We're quickly approaching our two-year anniversary, which will be on episode 105. To celebrate, we've created a unique t-shirt design, available for purchase until the end of August. Shirts will be shipped out around September 1st. Most of the proceeds will support the show, and specifically allow us to buy...

New discussion segment

2015-01-17

We're thinking about adding a new segment to the show where we discuss a topic that the listeners suggest. It's meant to be informative like a tutorial, but more of a "free discussion" format. If you have any subjects you want us to explore, or even just a good name...

How did you get into BSD?

2014-11-26

We've got a fun idea for the holidays this year: just like we ask during the interviews, we want to hear how all the viewers and listeners first got into BSD. Email us your story, either written or a video version, and we'll read and play some of them for...


Episode 216: Software is storytelling

2017-10-18

Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines EuroBSDcon Trip Report This is from Frank Moore, who has been supplying us with collections of links for the show and who we met at EuroBSDcon in Paris for the first time. Here is his trip report. My attendance at the...

Episode 215: Turning FreeBSD up to 100 Gbps

2017-10-11

Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines Serving 100 Gbps from an Open Connect Appliance In the summer of 2015, the Netflix Open Connect CDN team decided to take on an ambitious project. The goal was to leverage the new 100GbE network interface technology just coming to...

Episode 214: The history of man, kind

2017-10-04

Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines The Cost Of Open Sourcing Your Project Accusing a company of “dumping” their project as open source is probably misplaced – it’s an expensive business no-one would do frivolously. If you see an active move to change software licensing...

Episode 213: The French CONnection

2017-09-27

Direct Download:HD VideoMP3 AudioTorrent This episode was brought to you by Headlines Recap of EuroBSDcon 2017 in Paris, France EuroBSDcon was held in Paris, France this year, which drew record numbers this year. With over 300 attendees, it was the largest BSD event I have ever attended, and I was encouraged by the higher than...