---
title: "Early Adopter's Guide to FreeBSD 5.1-RELEASE"
sidenav: download
---

++++


        <div class="AUTHORGROUP">
          <a id="AEN4" name="AEN4"></a>

          <h3 class="CORPAUTHOR">The FreeBSD Release Engineering
          Team</h3>
        </div>

        <p class="COPYRIGHT">Copyright &copy; 2002, 2003 by The
        FreeBSD Release Engineering Team</p>

        <p class="PUBDATE">$FreeBSD:
        src/release/doc/en_US.ISO8859-1/early-adopter/article.sgml,v
        1.15 2003/05/03 22:14:55 bmah Exp $<br />
        </p>

        <div>
          <div class="ABSTRACT">
            <a id="AEN11" name="AEN11"></a>

            <p>This article describes the status of FreeBSD
            5.1-RELEASE, from the standpoint of users who may be
            new to the 5.<tt class="REPLACEABLE"><i>X</i></tt>
            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.</p>
          </div>
        </div>
        <hr />
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="INTRO" name="INTRO">1
        Introduction</a></h1>

        <p>FreeBSD 5.<tt class="REPLACEABLE"><i>X</i></tt> 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.<tt class="REPLACEABLE"><i>X</i></tt> releases, the first
        few 5.<tt class="REPLACEABLE"><i>X</i></tt> releases may
        have regressions in areas of stability, performance, and
        occasionally functionality.</p>

        <p>For these reasons, the Release Engineering Team <tt
        class="EMAIL">&#60;<a
        href="mailto:re@FreeBSD.org">re@FreeBSD.org</a>&#62;</tt>
        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.<tt
        class="REPLACEABLE"><i>X</i></tt> releases (such as
        4.8-RELEASE) for the near-term future. We feel that such
        users are probably best served by upgrading to 5.<tt
        class="REPLACEABLE"><i>X</i></tt> only after a 5-STABLE
        development branch has been created; this may be around the
        time of 5.2-RELEASE.</p>

        <p>(FreeBSD 5.<tt class="REPLACEABLE"><i>X</i></tt> 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!)</p>

        <p>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.<tt
        class="REPLACEABLE"><i>X</i></tt> systems to
        5.1-RELEASE.</p>
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="RELEASE-OVERVIEW"
        name="RELEASE-OVERVIEW">2 An Overview of the FreeBSD
        Release Process</a></h1>

        <p>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 <tt
        class="LITERAL">HEAD</tt> 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.</p>

        <p>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.<tt class="REPLACEABLE"><i>X</i></tt> releases
        were based on it. This branch has the tag <tt
        class="LITERAL">RELENG_4</tt> in the CVS repository.</p>

        <p>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).</p>

        <p>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 <tt
        class="LITERAL">RELENG_5</tt>. 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.</p>

        <p>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.<tt
        class="REPLACEABLE"><i>X</i></tt> series before this
        happens; we estimate that the 5-STABLE branch will be
        created sometime after 5.2-RELEASE.</p>

        <p>More information on FreeBSD release engineering
        processes can be found on the <a
        href="http://www.FreeBSD.org/releng/index.html"
        target="_top">Release Engineering Web pages</a> and in the
        <a
        href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/releng/index.html"
         target="_top">``FreeBSD Release Engineering''</a> article.
        Specific issues for the upcoming 5-STABLE development
        branch can be found in <a
        href="http://docs.freebsd.org/doc/5.1-RELEASE/usr/share/doc/en_US.ISO8859-1/articles/5-roadmap/index.html"
         target="_top">``The Roadmap for 5-STABLE''</a>.</p>
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="NEW" name="NEW">3 New
        Features</a></h1>

        <p>A large attraction of FreeBSD 5.<tt
        class="REPLACEABLE"><i>X</i></tt> 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:</p>

        <ul>
          <li>
            <p>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.</p>
          </li>

          <li>
            <p>KSE: Kernel Scheduled Entities allow a single
            process to have multiple kernel-level threads, similar
            to Scheduler Activations. The (experimental) <tt
            class="FILENAME">libkse</tt> and <tt
            class="FILENAME">libthr</tt> libraries make this
            feature available to multi-threaded userland
            programs.</p>
          </li>

          <li>
            <p>New architectures: Support for the sparc64 and ia64
            architectures, in addition to the i386, pc98, and
            alpha.</p>
          </li>

          <li>
            <p>GCC: The compiler toolchain is now based on GCC
            3.2.2, rather than GCC 2.95.<tt
            class="REPLACEABLE"><i>X</i></tt>.</p>
          </li>

          <li>
            <p>MAC: Support for extensible, loadable Mandatory
            Access Control policies.</p>
          </li>

          <li>
            <p>GEOM: A flexible framework for transformations of
            disk I/O requests. An experimental disk encryption
            facility has been developed based on GEOM.</p>
          </li>

          <li>
            <p>FFS: The FFS filesystem now supports background <a
            href="http://www.FreeBSD.org/cgi/man.cgi?query=fsck&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
            <span class="CITEREFENTRY"><span
            class="REFENTRYTITLE">fsck</span>(8)</span></a>
            operations (for faster crash recovery) and filesystem
            snapshots.</p>
          </li>

          <li>
            <p>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 <a
            href="http://www.FreeBSD.org/cgi/man.cgi?query=newfs&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
            <span class="CITEREFENTRY"><span
            class="REFENTRYTITLE">newfs</span>(8)</span></a>. On
            all platforms except for pc98, filesystems created from
            within <a
            href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
            <span class="CITEREFENTRY"><span
            class="REFENTRYTITLE">sysinstall</span>(8)</span></a>
            will use UFS2 by default.</p>
          </li>

          <li>
            <p>Cardbus: Support for Cardbus devices.</p>
          </li>
        </ul>

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

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="DRAWBACKS" name="DRAWBACKS">4
        Drawbacks to Early Adoption</a></h1>

        <p>Along with the new features of FreeBSD 5.<tt
        class="REPLACEABLE"><i>X</i></tt> 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:</p>

        <ul>
          <li>
            <p>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.</p>
          </li>

          <li>
            <p>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.</p>
          </li>

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

          <li>
            <p>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.</p>
          </li>

          <li>
            <p>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.</p>
          </li>

          <li>
            <p>Many FreeBSD 5.<tt class="REPLACEABLE"><i>X</i></tt>
            features are seeing wide exposure for the first time.
            Many of these features (such as SMPng) have broad
            impacts on the kernel.</p>
          </li>

          <li>
            <p>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.</p>
          </li>

          <li>
            <p>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.)</p>
          </li>

          <li>
            <p>Documentation (such as the FreeBSD <a
            href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/index.html"
             target="_top">Handbook</a> and <a
            href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html"
             target="_top">FAQ</a>) may not reflect changes
            recently made to FreeBSD 5.<tt
            class="REPLACEABLE"><i>X</i></tt>.</p>
          </li>
        </ul>

        <p>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.<tt
        class="REPLACEABLE"><i>X</i></tt> series is more
        polished.</p>
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="PLANS-STABLE"
        name="PLANS-STABLE">5 Plans for the 4-STABLE
        Branch</a></h1>

        <p>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 <tt class="LITERAL">HEAD</tt>
        at the discretion of developers, subject to existing
        release engineering policies.</p>

        <p>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).</p>

        <p>The Security Officer Team <tt class="EMAIL">&#60;<a
        href="mailto:security-officer@FreeBSD.org">security-officer@FreeBSD.org</a>&#62;</tt>
        will continue to support releases made from the 4-STABLE
        branch in accordance with their published policies, which
        can be found on the <a
        href="http://www.FreeBSD.org/security/index.html"
        target="_top">Security page</a> 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.</p>
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="UPGRADE" name="UPGRADE">6 Notes on
        Upgrading from FreeBSD 4.<tt
        class="REPLACEABLE"><i>X</i></tt></a></h1>

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

        <div class="SECT2">
          <hr />

          <h2 class="SECT2"><a id="AEN136" name="AEN136">6.1 Binary
          Upgrades</a></h2>

          <p>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).</p>

          <p>As of this time, the binary upgrade option in <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">sysinstall</span>(8)</span></a> 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.<tt
          class="REPLACEABLE"><i>X</i></tt> but not in 5.<tt
          class="REPLACEABLE"><i>X</i></tt>. These obsolete files
          may create some problems.</p>

          <p>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 <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=device.hints&amp;sektion=5&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">device.hints</span>(5)</span></a>
          mechanism (it allows specifying the same parameters, but
          with a very different interface).</p>

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

          <p>CDROM-based installations on the i386 architecture now
          use a ``no-emulation'' boot loader. This allows, among
          other things, the use of a <tt
          class="LITERAL">GENERIC</tt> 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.<tt class="REPLACEABLE"><i>X</i></tt>
          CDROMs.</p>
        </div>

        <div class="SECT2">
          <hr />

          <h2 class="SECT2"><a id="AEN158" name="AEN158">6.2 Source
          Upgrades</a></h2>

          <p>Reading <tt class="FILENAME">src/UPDATING</tt> 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.</p>
        </div>

        <div class="SECT2">
          <hr />

          <h2 class="SECT2"><a id="AEN164" name="AEN164">6.3 Common
          Notes</a></h2>

          <p><b class="APPLICATION">Perl</b> 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). <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">sysinstall</span>(8)</span></a>
          will now install the Perl package as a part of most
          distribution sets, so most users will not notice this
          change.</p>

          <p>It is generally possible to run old 4.<tt
          class="REPLACEABLE"><i>X</i></tt> executables under 5.<tt
          class="REPLACEABLE"><i>X</i></tt>, but this requires the
          <tt class="FILENAME">compat4x</tt> distribution to be
          installed. Thus, using old ports <span
          class="emphasis"><i class="EMPHASIS">may</i></span> be
          possible.</p>

          <p>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 <tt
          class="FILENAME">/usr/include</tt>. Renaming or moving
          this directory before a binary installation or an <tt
          class="LITERAL">installworld</tt> 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.</p>

          <p><tt class="FILENAME">MAKEDEV</tt> is no longer
          available, nor is it required. FreeBSD 5.<tt
          class="REPLACEABLE"><i>X</i></tt> uses a device
          filesystem, which automatically creates device nodes on
          demand. For more information, please see <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=devfs&amp;sektion=5&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">devfs</span>(5)</span></a>.</p>

          <p>UFS2 is the default on-disk format for file systems
          created using <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=newfs&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">newfs</span>(8)</span></a>. For all
          platforms except pc98, it is also the default for file
          systems created using the disk labeling screen within <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">sysinstall</span>(8)</span></a>.
          Because FreeBSD 4.<tt class="REPLACEABLE"><i>X</i></tt>
          only understands UFS1 (not UFS2), disk partitions that
          need to be accessed by both 5.<tt
          class="REPLACEABLE"><i>X</i></tt> and 4.<tt
          class="REPLACEABLE"><i>X</i></tt> must be created with
          UFS1. This can be specified using the <tt
          class="OPTION">-O1</tt> option to <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=newfs&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">newfs</span>(8)</span></a>, or on
          the disk labeling screen in <a
          href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&amp;sektion=8&amp;manpath=FreeBSD+5.1-release">
          <span class="CITEREFENTRY"><span
          class="REFENTRYTITLE">sysinstall</span>(8)</span></a>.
          This situation most often arises with a a single machine
          that dual-boots FreeBSD 4.<tt
          class="REPLACEABLE"><i>X</i></tt> and FreeBSD 5.<tt
          class="REPLACEABLE"><i>X</i></tt>. 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).</p>
        </div>
      </div>

      <div class="SECT1">
        <hr />

        <h1 class="SECT1"><a id="SUMMARY" name="SUMMARY">7
        Summary</a></h1>

        <p>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.<tt class="REPLACEABLE"><i>X</i></tt>
        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.</p>
      </div>
    </div>
    <hr />

    <p align="center"><small>This file, and other release-related
    documents, can be downloaded from <a
    href="ftp://ftp.FreeBSD.org/">ftp://ftp.FreeBSD.org/</a>.</small></p>

    <p align="center"><small>For questions about FreeBSD, read the
    <a href="http://www.FreeBSD.org/docs.html">documentation</a>
    before contacting &#60;<a
    href="mailto:questions@FreeBSD.org">questions@FreeBSD.org</a>&#62;.</small></p>

    <p align="center"><small><small>All users of FreeBSD 5-CURRENT
    should subscribe to the &#60;<a
    href="mailto:current@FreeBSD.org">current@FreeBSD.org</a>&#62;
    mailing list.</small></small></p>

    <p align="center">For questions about this documentation,
    e-mail &#60;<a
    href="mailto:doc@FreeBSD.org">doc@FreeBSD.org</a>&#62;.</p>
    <br />
    <br />
++++


