Tracking the FreeBSD Sources

The easiest and most common system upgrade path is simply to wait for each new official FreeBSD release. You get a copy of the CD or disk image file and install the new version of the operating system from it by using the methods covered in Chapter 2, or as described at the FreeBSD website.

However, new features that come with new major releases aren't the only reasons you might want to upgrade. Suppose, for example, that a major security flaw has been found in the kernel, or in a key system component such as BIND or Sendmail. This situation requires an immediate response, a real-time solution to a real-time problem. There's really only one way to achieve this end: You have to track the sources.

The source tree for FreeBSD is kept in a central Concurrent Versions System (CVS) repository, mirrored across a number of redundant servers, and maintained by a fairly small core of contributors and committers. FreeBSD is structured so that the entire system is available in source form at all times for anybody to use. This structure differs from the Linux model, in which the sources for the kernel are available but each individual, independent distribution of the complete operating system has its own set of executables and libraries, its own filesystem structure, and its own policies for how the source code for those resources should be made available. Whether you're a developer who intends to modify and develop the sources and check them back in to the main tree or a user who simply wants to maintain a server with a current source distribution, you use CVSand a utility called CVSupto interact with the source repository and get the up-to-date sources you need. This model gives FreeBSD developers and users the same level of access to the code.

Thus, when a security flaw has been patched or a critical bug fix has been checked into the source repository, you as a FreeBSD user have the ability to synchronize your sources with the most recent version and then build and install a new component to address your system's vulnerabilityor build an entirely new operating system from the ground up.

The STABLE and CURRENT Source Branches Explained

Between full operating system releases, the FreeBSD code is in a state of constant flux. Bugs are being fixed, utilities are being patched and extended, features are being added, and the structure of the system is being reorganized. To understand this process, think of the code repository as a tree that occasionally sprouts new branches at the top as it grows. Each time a new version of the FreeBSD code (5.x, 5.2.x, 6.x, and so on) is initiated, it branches off from the main development codebase (or the "trunk" of the tree). As shown in Figure 19.1, the topmost branch is called CURRENT, and the next highest is STABLE. Typically, multiple branches of the code tree are undergoing maintenance at the same time, with the two newest branches in active development and earlier branches receiving sporadic maintenance.

Figure 19.1. The FreeBSD code branches, showing the relationship of the CURRENT and STABLE branches.

This code development model is fairly common in the software world; it enables developers to freeze a certain feature set within a version and avoid the instability of ongoing minor tweaks and additions. Following this model, developers add new features in blocks, introducing each new feature set or restructuring with each new branch.

The thing to remember here is that CURRENT is not the branch you want to use for a production server! CURRENT refers to the very most cutting-edge branch of the codethe one where brand-new features are being tested. Consequently, it's the least stable branch of the code tree. CURRENT is intended only for developers and people who absolutely, without any possibility of alternative, must have the new features that are introduced in FreeBSD code, without waiting for them to be declared part of a STABLE version.

At some point during development on a CURRENT branchusually after the first release, for example 6.0-RELEASEthe CURRENT version feature set is deemed STABLE, and the CURRENT and STABLE designations each move up one branch on the tree. CURRENT becomes the tag for the newly created topmost branch, and the newly designated STABLE (formerly CURRENT) version feature set is now recommended for use on production servers. New releases are announced on both branches every few months, until the feature set in CURRENT has matured and the STABLE branch no longer meets the needs of the community. The tree then branches again, starting the cycle over.

Note

Of course, this model is an idealization of actual reality. FreeBSD 6.0 was released after a longer period between full releases than was characteristic of earlier version schedules, and it was a much less radical upgrade from the 5.x branch than FreeBSD 5.0 was from the 4.x branch. As of this writing, FreeBSD 6.x is the STABLE branch, but actively maintained STABLE branches exist for both 5.x and 4.x as well (many legacy users have still not upgraded from the 4.x codebase because of the major changes in the 5.x tree).

Selecting Your Upgrade Target

You can upgrade your system at any time, no matter how far along the development in the source tree is. You have three choices for making the upgrade:

• You can select any release in which the code is frozen and kept in a static repository.

• You can synchronize your source tree using the CVSup utility (in much the same way as we discussed synchronizing your ports in Chapter 16, "Installing Additional Software") to the "errata fix branch" for a particular release, receiving fixes for security vulnerabilities and serious bugs without requiring you to perform a major upgrade. This is the best method for most users.

• You can simply synchronize your source tree to a line of active development and build a new system from scratch any time you want to.

The remaining sections of this chapter discuss how to synchronize your source tree to a chosen release or development branch in order to update your FreeBSD system. The only difference, in practice, between the methods described here is the target branch tag you use in your CVSup configuration, the identifier that describes the FreeBSD version you want. All tags begin with RELENG, a prefix that stands for release engineer. The RELENG tag signifies that a branch has been officially initiated by the release engineer on the core FreeBSD team.

Note

See http://www.freebsd.org/releng/ for a current list of FreeBSD releases and their maintenance status.

Upgrading to a Release Version

To upgrade your FreeBSD system to a release version, you insert a release version tag into your CVSup configuration, which we will discuss a little later. The release version tags all have three digits, separated by underscores rather than periods, and have a suffix of RELEASE. Table 19.1 shows how release tags map to version numbers. This is an incomplete example; there are many more available release version numbers available, each with their corresponding tags.

Table 19.1. Mappings Between Release Tags and Version Numbers

Release Tag	Version Number
RELENG_6_0_0_RELEASE	FreeBSD 6.0
RELENG_5_4_0_RELEASE	FreeBSD 5.4
RELENG_5_2_1_RELEASE	FreeBSD 5.2.1
RELENG_4_11_0_RELEASE	FreeBSD 4.11

Upgrading to an Interim Build on an Errata Fix Branch

Interim versions for specific releases are maintained so you can apply security patches and critical code fixes to an otherwise unchanging RELEASE codebase. If your system is built from 5.4-RELEASE sources and you want to track a code branch that incorporates all the most recent security fixes without having to worry about all the other new features and code (and instabilities) that go into the STABLE development branch, you can synchronize your system to the RELENG_5_4 branch. This upgrade gives you RELENG_5_4_0_RELEASE, plus any critical patches that have been committed since then, but nothing that has gone exclusively into the 5.5 development tree.

Interim releases on a so-called "errata fix branch" (or, earlier, "security fix branch") such as RELENG_5_4 are numbered with a p suffix, as in 5.4-RELEASE-p3, which signifies a system built from the third revision that was checked into the RELENG_5_4 branch. From this you can see that code checkins in the errata fix branches are carefully managed and only occur in response to specific issues, such as to address security flaws or bugs that cause kernel panics.

Note

Security vulnerability announcements (such as those sent to the freebsd-securitynotifications mailing list) usually contain two suggested paths for fixing the bug in question: the point on each errata fix branch to which you need to upgrade your sources and then rebuild a component or the entire system, or a link to a "patch" file that you can apply to your existing sources without synchronizing the entire system. The instructions for downloading and applying the patch are given in the security bulletins, as well as instructions for rebuilding and reinstalling the affected component. However, in many cases, a bug fix is in the kernel or in a very basic system component, requiring you to rebuild the kernel or the entire system as described in the rest of this chapter. Using source patches is quick and convenient if possible, but you won't always have the luxury.

Errata fixes occur usually about once a month. Each such code change is marked with a sequential p number and publicized in a security announcement to the appropriate mailing list (you'll see more about the key mailing lists for tracking FreeBSD sources later in this chapter). These interim releases continue as long as the release is designated as being officially supported; refer to http://www.freebsd.org/releng/ to see which branches are supported and to know when support for a particular branch is dropped.

Tip

Use the uname -a command to see what version you're currently running:

# uname -a FreeBSD simba 5.4-RELEASE-p3 FreeBSD 5.4-RELEASE-p3 #1: Wed Jun 29 18: 06:56PDT 2005 root@simba:/usr/obj/usr/src/sys/GENERIC i386

To upgrade to an interim build of FreeBSD, you specify in your CVSup configuration an errata fix branch that's in development. To switch from a RELEASE version (such as your original installation) to its corresponding errata fix branch, create your release target by leaving off the RELEASE suffix and the third digit from the initial release's tag, as shown in Table 19.2.

Table 19.2. Branch Tags and Version Designations for Interim Versions

Branch Tag	Version Designation
RELENG_6_0	FreeBSD 6.0-RELEASE-p# errata fix branch
RELENG_5_4	FreeBSD 5.4-RELEASE-p# errata fix branch
RELENG_4_11	FreeBSD 4.11-RELEASE-p# errata fix branch

Tip

Note that Table 19.2 is current as of early 2006. Due to the dynamic nature of development branches, this information will become obsolete with time. Refer to http://www.freebsd.org/handbook/cvs-tags.html for a definitive and current table of the appropriate branch tags.

Upgrading to an Active Line of Development (CURRENT or STABLE)

Seasoned FreeBSD veterans (and only seasoned FreeBSD veterans) can ride the ragged edge of the system's development by synchronizing their sources with a code branch that's not a released version or an interim build. This is typically only necessary for FreeBSD developers and contributors with a demonstrated need for having access to the very latest code changes or experimental features, and who don't care about letting others test and endorse the code with regimented interim releases.

Tracking STABLE or CURRENT branches in this way means you specify a branch tag with only the first digit of the release branch. For instance, specifying RELENG_6 gives you the current state of the FreeBSD 6.x source tree, including code changes checked in by independent developers hours or minutes ago; it isn't tied to the official "frozen" states of FreeBSD 6.0, 6.1, or any other designated release. And that's just for the STABLE branches. You can get even more adventuresome by specifying the HEAD of the code tree, which gives you the CURRENT branchas you'll recall, CURRENT is where the newest, most experimental features are being actively developed, and they may not be stable or even complete. There's no guarantee that the code will be "safe" at any particular time, as it is with the interim p releases on an errata fix branch. If you choose to track a CURRENT or STABLE code branch, be prepared to wrestle with a system that may be unstable or even unusable if you happen to sync your sources to it at just the wrong time!

See Table 19.3 for the branch tags you'll use to sync to a CURRENT or STABLE branch.

Table 19.3. Branch Tags for Active Development Branches

Branch Tag	Version Designation
HEAD	FreeBSD-CURRENT (the very most recent code, not yet designated with an official version number). In CVSup, use a period (.) instead of HEAD as the branch tag.
RELENG_6	FreeBSD 6-STABLE (the main line of 6.x development)
RELENG_5	FreeBSD 5-STABLE (the main line of 5.x development)
RELENG_4	FreeBSD 4-STABLE (the main line of 4.x development)