Early Adopter's Guide to FreeBSD 5.2.1-RELEASE

1 Introduction

FreeBSD 5.X marks the first new major version of FreeBSD in over two years. Besides a number of new features, it also contains a number of major developments in the underlying system architecture. Along with these advances, however, comes a system that incorporates a tremendous amount of new and not-widely-tested code. Compared to the existing line of 4.X releases, the first few 5.X releases may have regressions in areas of stability, performance, and occasionally functionality.

For these reasons, the Release Engineering Team <re@FreeBSD.org> specifically discourages users from updating from older FreeBSD releases to 5.2.1-RELEASE unless they are aware of (and prepared to deal with) possible regressions in the newer releases. Specifically, for more conservative users, we recommend running 4.X releases (such as 4.9-RELEASE) for the near-term future. We feel that such users are probably best served by upgrading to 5.X only after a 5-STABLE development branch has been created; this may be around the time of 5.3-RELEASE.

(FreeBSD 5.X suffers from what has been described as a ``chicken and egg'' problem. The entire project has a goal of producing releases that are as stable and reliable as possible. This stability and reliability requires widespread testing, particularly of the system's newer features. However, getting a large number of users to test the system, in a practical sense, means building and distributing a release first!)

This article describes some of the issues involved in installing and running FreeBSD 5.2.1-RELEASE. We begin with a brief overview of the FreeBSD release process. We then present some of the more noteworthy new features in FreeBSD 5.2.1-RELEASE, along with some areas that may prove troublesome for unwary users. For those users choosing to remain with 4-STABLE-based releases, we give some of the short- to medium-term plans for this development branch. Finally, we present some notes on upgrading existing 4.X systems to 5.2.1-RELEASE.

2 An Overview of the FreeBSD Release Process

FreeBSD employs a model of development that relies on multiple development branches within the source code repository. The main branch is called ``CURRENT'', and is referred to in the CVS repository with the HEAD tag. New features are committed first to this branch; although this means that CURRENT is the first to see new functionality, it also means that it occasionally suffers from breakages as new features are added and debugged.

Most FreeBSD releases are made from one of several ``STABLE'' branches. Features are only added to these branches after some amount of testing in CURRENT. At the moment, only one STABLE branch is under active development; this branch is referred to as ``4-STABLE'', and all of the FreeBSD 4.X releases were based on it. This branch has the tag RELENG_4 in the CVS repository.

FreeBSD 5.0, 5.1, and 5.2 are based on the CURRENT branch. The first of these releases was made after over two years of development (prior to these, the last release from HEAD was FreeBSD 4.0, in March 2000).

At some point after the release of FreeBSD 5.0, a ``5-STABLE'' branch will be created in the FreeBSD CVS repository with the branch tag RELENG_5. The past two stable branches (3-STABLE and 4-STABLE) were created immediately after their respective ``dot-oh'' releases (3.0 and 4.0, respectively). In hindsight, this practice did not give sufficient time for either CURRENT to stabilize before the new branches were created. This in turn resulted in wasted effort porting bug fixes between branches, as well as some architectural changes that could not be ported between branches at all.

Therefore, the release engineering team will only create the 5-STABLE branch in the CVS repository after we have found a relatively stable state to use as its basis. It is likely that there will be multiple releases in the 5.X series before this happens; we estimate that the 5-STABLE branch will be created around the time of 5.3-RELEASE.

More information on FreeBSD release engineering processes can be found on the Release Engineering Web pages and in the ``FreeBSD Release Engineering'' article. Specific issues for the upcoming 5-STABLE development branch can be found in ``The Roadmap for 5-STABLE''.

3 New Features

A large attraction of FreeBSD 5.X is a number of new features. These new features and functionality generally involve large architectural changes that were not feasible to port back to the FreeBSD 4-STABLE development branch. (By contrast, many self-contained enhancements, such as new device drivers or userland utilities, have already been ported.) A brief, but not exhaustive list includes:

• SMPng: The ``next generation'' support for SMP machines (work in progress). Ongoing work aims to perform fine-grained locking of various kernel subsystems to increase the number of threads of execution that can be running in the kernel.

• KSE: Kernel Scheduled Entities allow a single process to have multiple kernel-level threads, similar to Scheduler Activations. The libkse and libthr threading libraries make this feature available to multi-threaded userland programs, using the pthread(3) API.

• New architectures: Support for the sparc64, ia64, and amd64 architectures, in addition to the i386, pc98, and alpha.

• GCC: The compiler toolchain is now based on GCC 3.3.X, rather than GCC 2.95.X.

• MAC: Support for extensible, loadable Mandatory Access Control policies.

• GEOM: A flexible framework for transformations of disk I/O requests. The GBDE experimental disk encryption facility has been developed based on GEOM.

• FFS: The FFS filesystem now supports background fsck(8) operations (for faster crash recovery) and filesystem snapshots.

• UFS2: A new UFS2 on-disk format has been added, which supports extended per-file attributes and larger file sizes. UFS2 is now the default format for newfs(8). On all platforms except for pc98, filesystems created from within sysinstall(8) will use UFS2 by default.

• Cardbus: Support for Cardbus devices.

• Bluetooth: Support for Bluetooth devices.

A more comprehensive list of new features can be found in the release notes for the various FreeBSD 5.X releases.

4 Drawbacks to Early Adoption

Along with the new features of FreeBSD 5.X come some areas that can cause problems, or at least can lead to unexpected behavior. Generally, these come from the fact that a number of features are works-in-progress. A partial list of these areas of difficulty includes:

• A number of features are not yet finished. Examples from the feature list above include SMPng and KSE. While suitable for testing and experimentation, these features may not be ready for production use.

• Because of changes in kernel data structures and ABIs/APIs, third-party binary device drivers will require modifications to work correctly under FreeBSD 5.0. There is a possibility of more minor ABI/API changes before the 5-STABLE branch is created, particularly on newer machine architectures. In some (hopefully rare) cases, user-visible structures may change, requiring recompiling of applications or reinstallation of ports/packages.

• Several parts of FreeBSD's base system functionality have been moved to the Ports Collection. Notable examples include Perl, UUCP, and most (but not all) games. While these programs are still supported, their removal from the base system may cause some confusion.

• Some parts of the FreeBSD base system have fallen into a state of disrepair due to a lack of users and maintainers. These have been removed. Specific examples include the generation of a.out-style executables, XNS networking support, and the X-10 controller driver.

• A number of ports and packages do not build or do not run correctly under FreeBSD 5.X, whereas they did under FreeBSD 4-STABLE. Generally these problems are caused by compiler toolchain changes or cleanups of header files. In some cases they are caused by changes in kernel or device support.

• Many FreeBSD 5.X features are seeing wide exposure for the first time. Many of these features (such as SMPng) have broad impacts on the kernel, and it may be difficult to gauge their effects on stability and performance.

• A certain amount of debugging and diagnostic code is still in place to help track down problems in FreeBSD 5.X's new features. This may cause FreeBSD 5.X to perform more slowly than 4-STABLE.

• Features are only added to the 4-STABLE development branch after a ``settling time'' in -CURRENT. FreeBSD 5.X does not have the stabilizing influence of a -STABLE branch. (It is likely that the 5-STABLE development branch will be created sometime after 5.3-RELEASE.)

• Documentation (such as the FreeBSD Handbook and FAQ) may not reflect changes recently made to FreeBSD 5.X.

Because a number of these drawbacks affect system stability, the release engineering team recommends that more conservative sites and users stick to releases based on the 4-STABLE branch until the 5.X series is more polished. While we believe that many initial problems with stability have been fixed, some issues with performance are still being addressed by works-in-progress. We also note that best common practices in system administration call for trying operating system upgrades in a test environment before upgrading one's production, or ``mission-critical'' systems.

5 Plans for the 4-STABLE Branch

It is important to note that even though releases are being made in the 5.X series, support for 4.X releases will continue for some time. Indeed, FreeBSD 4.8 was released two months after 5.0, in April 2003, followed by 4.9, in October 2003. Future releases from the 4-STABLE branch (if any) will depend on several factors. The most important of these is the existence and stability of the 5-STABLE branch. If CURRENT is not sufficiently stable to allow the creation of a 5-STABLE branch, this may require and permit more releases from the 4-STABLE branch. Until the last declared release on the 4-STABLE branch, new features may be merged from HEAD at the discretion of developers, subject to existing release engineering policies.

To some extent, the release engineering team (as well as the developer community as a whole) will take into account user demand for future 4-STABLE releases. This demand, however, will need to be balanced with release engineering resources (particularly developers' time, computing resources, and mirror archive space). We note that in general, the FreeBSD community (both users and developers) has shown a preference for moving forward with new features in the 5.X branch and beyond, due to the difficulty involved in backporting (and maintaining) new functionality in 4.X.

The Security Officer Team <security-officer@FreeBSD.org> will continue to support releases made from the 4-STABLE branch in accordance with their published policies, which can be found on the Security page on the FreeBSD web site. Generally, the two most recent releases from any branch will be supported with respect to security advisories and security fixes. At its discretion, the team may support other releases for specific issues.

At this point, the release engineering team has no specific plans for future releases from the 4-STABLE development branch. It seems likely that any future releases (if any) from this branch will be lightweight, ``point'' releases. These will probably carry 4.9.X version numbers, to indicate that they are not intended to provide large amount of new functionality compared to 4.9-RELEASE. In general, these releases will emphasize security fixes, bug fixes, and device driver updates (particularly to accommodate new hardware easily supported by existing drivers). Major new features (especially those requiring infrastructure support added in 5.X) will probably not be added in these releases.

6 Notes on Upgrading from FreeBSD 4.X

For those users with existing FreeBSD systems, this section offers a few notes on upgrading a FreeBSD 4.X system to 5.X. As with any FreeBSD upgrade, it is crucial to read the release notes and the errata for the version in question, as well as src/UPDATING in the case of source upgrades.

7 Summary

While FreeBSD 5.2.1-RELEASE contains a number of new and exciting features, it may not be suitable for all users at this time. In this document, we presented some background on release engineering, some of the more notable new features of the 5.X series, and some drawbacks to early adoption. We also presented some future plans for the 4-STABLE development branch and some tips on upgrading for early adopters.