Early Adopter's Guide to FreeBSD 5.1-RELEASE

  The FreeBSD Release Engineering Team

   Copyright (c) 2002, 2003 by The FreeBSD Release Engineering Team

   $FreeBSD: src/release/doc/en_US.ISO8859-1/early-adopter/article.sgml,v
   1.15 2003/05/03 22:14:55 bmah Exp $

   This article describes the status of FreeBSD 5.1-RELEASE, from the
   standpoint of users who may be new to the 5.X series of releases or to
   FreeBSD in general. It presents some background information on release
   engineering, some highlights of new features, and some possible drawbacks
   that might be faced by early adopters. It also contains some of the future
   release engineering plans for the 4-STABLE development branch and some
   tips on upgrading existing systems.

     ----------------------------------------------------------------------

     ----------------------------------------------------------------------

                                 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.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.8-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.2-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.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.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.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 and 5.1 are based on the CURRENT branch. These are the first
   releases from this branch in over two years (the last 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 sometime after 5.2-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). There is now partial support for multiple processors to be
       running in the kernel at the same time. This work is ongoing.

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

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

     * GCC: The compiler toolchain is now based on GCC 3.2.2, 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.
       An 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.

   A more comprehensive list of new features can be found in the release
   notes for FreeBSD 5.0-RELEASE and FreeBSD 5.1-RELEASE.

     ----------------------------------------------------------------------

                         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.

     * 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.0, whereas they did under FreeBSD 4-STABLE. Generally
       these problems are caused by compiler toolchain changes or cleanups of
       header files.

     * 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.

     * A certain amount of debugging and diagnostic code is still in place to
       help track down problems in FreeBSD 5.0's new features. This may cause
       FreeBSD 5.0 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.0 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.2-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.

     ----------------------------------------------------------------------

                        5 Plans for the 4-STABLE Branch

   The release of FreeBSD 5.0 does not mean the end of the 4-STABLE branch.
   Indeed, FreeBSD 4.8 was released two months after 5.0, in April 2003.
   There will most likely be at least one more release on this branch, namely
   4.9-RELEASE, currently scheduled for summer 2003. A 4.10-RELEASE is a
   likely possibility as well. Future releases from this branch 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).

   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.

     ----------------------------------------------------------------------

                     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.

     ----------------------------------------------------------------------

6.1 Binary Upgrades

   Probably the most straightforward approach is that of ``backup everything,
   reformat, reinstall, and restore everything''. This eliminates problems of
   incompatible or obsolete executables or configuration files polluting the
   new system. It allows new filesystems to be created to take advantage of
   new functionality (most notably, the UFS2 defaults).

   As of this time, the binary upgrade option in sysinstall(8) has not been
   well-tested for cross-major-version upgrades. Using this feature is not
   recommended. In particular, a binary upgrade will leave behind a number of
   files that are present in FreeBSD 4.X but not in 5.X. These obsolete files
   may create some problems.

   On the i386 and pc98 platforms, a UserConfig utility exists on 4-STABLE to
   allow boot-time configuration of ISA devices when booting from
   installation media. Under FreeBSD 5.0, this functionality has been
   replaced in part by the device.hints(5) mechanism (it allows specifying
   the same parameters, but with a very different interface).

   Floppy-based binary installations may require downloading a third, new
   floppy image holding additional device drivers in kernel modules. This
   drivers.flp floppy image will generally be found in the same location as
   the usual kern.flp and mfsroot.flp floppy images.

   CDROM-based installations on the i386 architecture now use a
   ``no-emulation'' boot loader. This allows, among other things, the use of
   a GENERIC kernel, rather than the stripped-down kernel on the floppy
   images. In theory, any system capable of booting the Microsoft Windows NT
   4 installation CDROMs should be able to cope with the FreeBSD 5.X CDROMs.

     ----------------------------------------------------------------------

6.2 Source Upgrades

   Reading src/UPDATING is absolutely essential. The section entitled ``To
   upgrade from 4.x-stable to current'' contains a step-by-step update
   procedure. This procedure must be followed exactly, without making use of
   the ``shortcuts'' that some users occasionally employ.

     ----------------------------------------------------------------------

6.3 Common Notes

   Perl has been removed from the base system, and should be installed either
   from a pre-built package or from the Ports Collection. Building Perl as a
   part of the base system created a number of difficulties which made
   updates problematic. The base system utilities that used Perl have either
   been rewritten (if still applicable) or discarded (if obsolete).
   sysinstall(8) will now install the Perl package as a part of most
   distribution sets, so most users will not notice this change.

   It is generally possible to run old 4.X executables under 5.X, but this
   requires the compat4x distribution to be installed. Thus, using old ports
   may be possible.

   When installing or upgrading over the top of an existing 4-STABLE-based
   system, it is extremely important to clear out old header files in
   /usr/include. Renaming or moving this directory before a binary
   installation or an installworld is generally sufficient. If this step is
   not taken, confusion may result (especially with C++ programs) as the
   compiler may wind up using a mixture of obsolete and current header files.

   MAKEDEV is no longer available, nor is it required. FreeBSD 5.X uses a
   device filesystem, which automatically creates device nodes on demand. For
   more information, please see devfs(5).

   UFS2 is the default on-disk format for file systems created using
   newfs(8). For all platforms except pc98, it is also the default for file
   systems created using the disk labeling screen within sysinstall(8).
   Because FreeBSD 4.X only understands UFS1 (not UFS2), disk partitions that
   need to be accessed by both 5.X and 4.X must be created with UFS1. This
   can be specified using the -O1 option to newfs(8), or on the disk labeling
   screen in sysinstall(8). This situation most often arises with a a single
   machine that dual-boots FreeBSD 4.X and FreeBSD 5.X. Note that there is no
   way to convert file systems between the two on-disk formats (other than
   backing up, re-creating the file system, and restoring).

     ----------------------------------------------------------------------

                                   7 Summary

   While FreeBSD 5.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.

     ----------------------------------------------------------------------

     This file, and other release-related documents, can be downloaded from
                            ftp://ftp.FreeBSD.org/.

     For questions about FreeBSD, read the documentation before contacting
                            <questions@FreeBSD.org>.

  All users of FreeBSD 5-CURRENT should subscribe to the <current@FreeBSD.org>
                                 mailing list.

       For questions about this documentation, e-mail <doc@FreeBSD.org>.