---
title: "FreeBSD 5.3-RELEASE Migration Guide"
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, 2004 The FreeBSD Release Engineering
Team</p>

<p class="PUBDATE">$FreeBSD: src/release/doc/en_US.ISO8859-1/early-adopter/article.sgml,v
1.21.2.4 2004/10/06 05:55:51 bmah Exp $<br />
</p>

<div class="LEGALNOTICE"><a id="TRADEMARKS" name="TRADEMARKS"></a>
<p>FreeBSD is a registered trademark of Wind River Systems, Inc. This is expected to
change soon.</p>

<p>Apple, FireWire, Mac, Macintosh, Mac OS, Quicktime, and TrueType are trademarks of
Apple Computer, Inc., registered in the United States and other countries.</p>

<p>IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, and ThinkPad are trademarks
of International Business Machines Corporation in the United States, other countries, or
both.</p>

<p>IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical and
Electronics Engineers, Inc. in the United States.</p>

<p>Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, and Xeon are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States and
other countries.</p>

<p>AMD, Athlon, Opteron, and Geode are trademarks or registered
trademarks of Advanced Micro Devices, Inc. in the United States
and other countries.</p>

<p>Microsoft, IntelliMouse, MS-DOS, Outlook, Windows, Windows Media and Windows NT are
either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.</p>

<p>Sparc, Sparc64, SPARCEngine, and UltraSPARC are trademarks of SPARC International, Inc
in the United States and other countries. Products bearing SPARC trademarks are based
upon architecture developed by Sun Microsystems, Inc.</p>

<p>Many of the designations used by manufacturers and sellers to distinguish their
products are claimed as trademarks. Where those designations appear in this document, and
the FreeBSD Project was aware of the trademark claim, the designations have been followed
by the ``&trade;'' or the ``&reg;'' symbol.</p>
</div>

<div>
<div class="ABSTRACT"><a id="AEN23" name="AEN23"></a>
<p>This article describes major differences between FreeBSD 4.<var
class="REPLACEABLE">X</var> and FreeBSD 5.3-RELEASE, from the viewpoint of a user or
administrator upgrading an existing system. It provides a brief overview of FreeBSD
release engineering. It then describes some of the new features in FreeBSD 5.<var
class="REPLACEABLE">X</var>, as well as some changes that might be of particular interest
to users accustomed to working with the 4.<var class="REPLACEABLE">X</var> series of
releases. This article also describes binary- and source-based upgrading procedures for
existing systems. An earlier version of this article appeared in prior FreeBSD 5.<var
class="REPLACEABLE">X</var> releases as the ``Early Adopters Guide''.</p>
</div>
</div>

<hr />
</div>

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

<p>FreeBSD 5.3-RELEASE marks the beginning of a new ``FreeBSD-STABLE'' series of
releases. This and future releases in the 5.<var class="REPLACEABLE">X</var> series will
be targeted toward production usage in much the same way as the prior 4.<var
class="REPLACEABLE">X</var> series of releases.</p>

<p>This article addresses a number of topics and issues of interest to users updating
from a 4.<var class="REPLACEABLE">X</var> release to 5.3-RELEASE. It begins with a brief
overview of current release engineering practices and then describes some of the new
features available with the FreeBSD 5.<var class="REPLACEABLE">X</var> series. Perhaps
the most important section lists issues where major changes have taken place,
user-visible behavior has changed, or external software interfaces have been modified.
Last are some notes on upgrading existing FreeBSD 4.<var class="REPLACEABLE">X</var>
systems to FreeBSD 5.3-RELEASE, from binaries or from source.</p>
</div>

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

<p>FreeBSD employs a development model relying on multiple branches within the source
code repository. The main branch is called ``CURRENT'', and is referred to in the CVS
repository with the <var class="LITERAL">HEAD</var> tag. New features are committed first
to this branch; although CURRENT is the first to see new functionality, it also
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
added to these branches only after some amount of testing in CURRENT. For the past two
years, the only STABLE branch under active development was known as ``4-STABLE'', and all
of the FreeBSD 4.<var class="REPLACEABLE">X</var> releases were based on it. This branch
has the tag <var class="LITERAL">RELENG_4</var> in the CVS repository.</p>

<p>The past two stable branches (3-STABLE and 4-STABLE) were created very early in their
development cycles (their branchpoints were 3.1 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 creating some architectural changes that could not be ported between
branches at all.</p>

<p>The 5.<var class="REPLACEABLE">X</var> releases have been handled slightly
differently. FreeBSD 5.0, 5.1, and 5.2 were 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).</p>

<p>Unlike prior ``STABLE'' branches, the ``5-STABLE'' branch in CVS (with the branch tag
<var class="LITERAL">RELENG_5</var>) was created more than a year after the first 5.<var
class="REPLACEABLE">X</var> release (specifically, during the 5.3 release cycle). This
delay gave time for the development team to complete needed architectural changes,
stabilize the system, finalize various interfaces, and create a good starting point for
the remaining 5.<var class="REPLACEABLE">X</var> releases.</p>

<p>Aside from general improvements and bug fixes, a major priority for development on the
5-STABLE branch is the preservation of Application Binary Interface (ABI) and Application
Program Interface (API) compatibility. Any changes that could break backward
compatibility (including kernel or library interfaces) are strongly discouraged, and will
not be permitted except as a last-resort solution to a critical problem.</p>

<p>The next release from CURRENT will likely be 6.0-RELEASE, created from CVS <var
class="LITERAL">HEAD</var>. There is no firm date for 6.0, as of the 5.3 release date,
although it is expected sometime in 2006.</p>

<p>A limited amount of development will continue on the 4-STABLE development branch, with
at least one more release (4.11) planned at some point after 5.3-RELEASE. For especially
conservative users, it may be reasonable to continue using the 4.<var
class="REPLACEABLE">X</var> releases for a time. The Security Officer Team <code
class="EMAIL">&#60;<a
href="mailto:security-officer@FreeBSD.org">security-officer@FreeBSD.org</a>&#62;</code>
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.</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.</p>
</div>

<div class="SECT1">
<hr />
<h2 class="SECT1"><a id="NEW" name="NEW">3 New Features</a></h2>

<p>A major attraction of FreeBSD 5.<var class="REPLACEABLE">X</var> is a number of new
features, generally involving 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 updates to userland utilities, have already
been ported.) A brief, but not exhaustive list includes:</p>

<ul>
<li>
<p>SMPng: The ``next generation'' support for Symmetric MultiProcessor (SMP) machines.
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. Particular
attention has been paid to the performance of the network stack.</p>
</li>

<li>
<p>KSE: Kernel Scheduled Entities allow a single process to have multiple kernel-level
threads, similar to Scheduler Activations. The <tt class="FILENAME">libpthread</tt> and
<tt class="FILENAME">libthr</tt> threading libraries make this feature available to
multi-threaded userland programs, using the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=pthread&sektion=3&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">pthread</span>(3)</span></a> API.
<tt class="FILENAME">libpthread</tt> is now the default threading library.</p>
</li>

<li>
<p>New architectures: Support for the amd64, ia64, pc98, and sparc64 architectures, in
addition to the i386 and alpha. Other platforms under development include powerpc (which
runs on many <span class="TRADEMARK">PowerPC</span>&reg;-based <span
class="TRADEMARK">Macintosh</span>&reg; platforms) and arm.</p>
</li>

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

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

<li>
<p>GEOM: A flexible, modular framework for transformation of disk I/O requests. This
system supports a number of features related to disks and volumes, such as: recognition
of disk partitions, the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=gbde&sektion=4&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">gbde</span>(4)</span></a> disk
encryption facility, various levels of RAID functionality, network export of disk devices
(with <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=ggated&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">ggated</span>(8)</span></a> and
related utilities), and transparent disk decompression.</p>
</li>

<li>
<p>FFS: The FFS file system now supports background <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=fsck&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">fsck</span>(8)</span></a>
operations (for faster crash recovery) and file system 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&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">newfs</span>(8)</span></a>. On all
platforms except pc98, file systems created from within <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">sysinstall</span>(8)</span></a>
will use UFS2 by default.</p>
</li>

<li>
<p>New networking features: A number of new networking features have made their debut in
5.<var class="REPLACEABLE">X</var> releases, including support for TCP SACK (selective
acknowledgements), the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=pf&sektion=4&manpath=FreeBSD+5.3-RELEASE"><span
 class="CITEREFENTRY"><span class="REFENTRYTITLE">pf</span>(4)</span></a> packet filter
from OpenBSD, and the ALTQ packet queueing system.</p>
</li>

<li>
<p>New hardware support: Support for more hardware devices, such as Cardbus, Bluetooth
devices, and IEEE 802.11a/b/g network interfaces based on Atheros chipsets. Also, on the
i386 architecture, some network devices not explicitly supported by FreeBSD drivers may
be supported using vendor drivers for <span class="TRADEMARK">Microsoft</span>&reg; <span
class="TRADEMARK">Windows</span>&reg; and the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=ndis&sektion=4&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">ndis</span>(4)</span></a>
compatibility layer.</p>
</li>
</ul>

<p>A more comprehensive list of new features can be found in the release notes for the
various FreeBSD 5.<var class="REPLACEABLE">X</var> releases.</p>
</div>

<div class="SECT1">
<hr />
<h2 class="SECT1"><a id="DRAWBACKS" name="DRAWBACKS">4 Notable Changes</a></h2>

<p>Some of the differences between FreeBSD 4.<var class="REPLACEABLE">X</var> and 5.<var
class="REPLACEABLE">X</var> deserve special mention because they involve major
architectural changes, or break backwards compatibility in some way. While these changes
are unlikely to cause a loss of data, they could cause some confusion for the unwary.
Some notable examples are:</p>

<ul>
<li>
<p>Several parts of FreeBSD's base system functionality have been moved to the FreeBSD
Ports Collection, usually because they are easier to maintain in that form or because
they were not really essential parts of the system. The most noticeable example of this
is <b class="APPLICATION">Perl</b> (available in the FreeBSD Ports Collection as <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/lang/perl5.8/pkg-descr"><tt
class="FILENAME">lang/perl5.8</tt></a>), whose former location in the base system made
upgrades problematic. Utilities in the base system that formerly relied on <b
class="APPLICATION">Perl</b> have been either rewritten (if still applicable) or removed
(if obsolete).</p>

<p>&#13;</p>

<p>Other examples include <b class="APPLICATION">UUCP</b> (available in the Ports
Collection as <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/net/freebsd-uucp/pkg-descr"><tt
class="FILENAME">net/freebsd-uucp</tt></a>), the <tt class="COMMAND">doscmd</tt> utility
(<a href="http://www.FreeBSD.org/cgi/url.cgi?ports/emulators/doscmd/pkg-descr"><tt
class="FILENAME">emulators/doscmd</tt></a>), and many of the traditional games (<a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/games/freebsd-games/pkg-descr"><tt
class="FILENAME">games/freebsd-games</tt></a>).</p>
</li>

<li>
<p>Changes in kernel data structures and ABIs/APIs meant many third-party binary device
drivers had to be modified before they would work correctly under FreeBSD 5.<var
class="REPLACEABLE">X</var>. In some (hopefully rare) cases, user-visible data structures
have changed, requiring recompilation of applications or reinstallation of
ports/packages. As with the 4.<var class="REPLACEABLE">X</var> series, the FreeBSD
development team has the goal of not allowing incompatible changes in future releases on
the 5.<var class="REPLACEABLE">X</var> branch.</p>
</li>

<li>
<p>A shortage of users and maintainers caused some parts of the FreeBSD base system to
fall into disrepair. These have been removed. Examples include the generation of <tt
class="FILENAME">a.out</tt>-style executables, <a id="AEN159" name="AEN159"
href="#FTN.AEN159"><span class="footnote">[1]</span></a> XNS networking support, and the
X-10 controller driver. A number of other drivers for old ISA-based devices have been
discovered to be non-working and have been removed. More details are given in the release
notes.</p>
</li>

<li>
<p>On FreeBSD/i386 4.<var class="REPLACEABLE">X</var>, the configuration of ISA devices
was initially specified in the kernel configuration. These could be modified at boot-time
with an interactive <b class="APPLICATION">UserConfig</b> utility. On FreeBSD 5.<var
class="REPLACEABLE">X</var>, both of these mechanisms have been replaced by the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=device.hints&sektion=5&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">device.hints</span>(5)</span></a>
mechanism, which eliminates the need to hard-code ISA configuration parameters in the
kernel. Boot-time ISA configuration is no longer menu-driven, but is performed by
entering new parameters to the boot loader command line prompt.</p>
</li>

<li>
<p><tt class="FILENAME">MAKEDEV</tt> is no longer available, nor is it required. FreeBSD
5.<var class="REPLACEABLE">X</var> uses a device file system, which automatically creates
device nodes on demand. Configuration of the entries in the device filesystem can be
performed with the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=devfs&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">devfs</span>(8)</span></a> utility
or with the <tt class="FILENAME">/etc/devfs.conf</tt> mechanism. More information can be
found in the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=devfs&sektion=5&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">devfs</span>(5)</span></a> manual
page.</p>
</li>

<li>
<p>UFS2 is the default on-disk format for file systems created using <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=newfs&sektion=8&manpath=FreeBSD+5.3-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&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">sysinstall</span>(8)</span></a>.
Because FreeBSD 4.<var class="REPLACEABLE">X</var> only understands UFS1 (not UFS2), disk
partitions that must be accessed by both 5.<var class="REPLACEABLE">X</var> and 4.<var
class="REPLACEABLE">X</var> must be created with UFS1. This can be specified using the
<var class="OPTION">-O1</var> option to <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=newfs&sektion=8&manpath=FreeBSD+5.3-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&sektion=8&manpath=FreeBSD+5.3-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.<var
class="REPLACEABLE">X</var> and FreeBSD 5.<var class="REPLACEABLE">X</var>. 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>
</li>

<li>
<p>Due to the upgraded <b class="APPLICATION">GCC</b> compiler, C++ programs generally
need to be recompiled and reinstalled. This requirement comes from changes in the C++
ABI.</p>
</li>

<li>
<p>Running executables compiled for FreeBSD 4.<var class="REPLACEABLE">X</var> may be
possible with the aid of the <tt class="FILENAME">compat4x</tt> distribution (or the
equivalent <a href="http://www.FreeBSD.org/cgi/url.cgi?ports/misc/compat4x/pkg-descr"><tt
class="FILENAME">misc/compat4x</tt></a> package/port). However, if any of the ports or
packages on a system require upgrading, rebuilding and reinstalling <span
class="emphasis"><i class="EMPHASIS">all</i></span> of the installed ports on a system is
generally advised. This will prevent problems that can occur with programs being linked
against some combination of old and new libraries. The <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/sysutils/portupgrade/pkg-descr"><tt
class="FILENAME">sysutils/portupgrade</tt></a> utility may be helpful in reinstalling
ports.</p>

<p>Note that in any case, there are a number of known instances of backward
incompatibility. For example, the <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/devel/gnomevfs2/pkg-descr"><tt
class="FILENAME">devel/gnomevfs2</tt></a>, <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/mail/postfix/pkg-descr"><tt
class="FILENAME">mail/postfix</tt></a>, and <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/security/cfs/pkg-descr"><tt
class="FILENAME">security/cfs</tt></a> ports need to be recompiled due to changes in the
<var class="LITERAL">statfs</var> structure.</p>
</li>

<li>
<p>The <tt class="FILENAME">host.conf</tt> resolver services configuration file has been
replaced by the (much more general) <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=nsswitch.conf&sektion=5&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">nsswitch.conf</span>(5)</span></a>
name-service switch configuration mechanism.</p>
</li>

<li>
<p><b class="APPLICATION">BIND</b> has been updated from version 8 to version 9. There
are numerous differences between BIND 8 and 9. Users with critical <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=named&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">named</span>(8)</span></a>
installations should read the migration documentation in <tt
class="FILENAME">/usr/share/doc/bind9/misc/migration</tt>. There is also a new
instruction manual in <tt class="FILENAME">/usr/share/doc/bind9/arm</tt>. On systems that
run <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=named&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">named</span>(8)</span></a>, it now
runs by default in a <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=chroot&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">chroot</span>(8)</span></a>
environment in <tt class="FILENAME">/var/named</tt>. Users with existing <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=named&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">named</span>(8)</span></a>
configurations in <tt class="FILENAME">/var/named</tt> should back up the contents of
this directory before upgrading to avoid them being overwritten by the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=named&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">named</span>(8)</span></a> startup
script.</p>
</li>

<li>
<p>The <b class="APPLICATION">Xorg</b> implementation of the X Window System is the
default for FreeBSD 5.<var class="REPLACEABLE">X</var> beginning with 5.3-RELEASE. As of
this writing, <b class="APPLICATION"><span class="TRADEMARK">XFree86</span>&#8482;</b>
remains the default for FreeBSD 4.<var class="REPLACEABLE">X</var>. More information on
the differences between these versions, as well as upgrade information for existing
systems, can be found in the <a
href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/x11.html" target="_top">X
Window System</a> chapter in the FreeBSD Handbook.</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>) is still being updated to reflect changes recently made to FreeBSD
5.<var class="REPLACEABLE">X</var>.</p>
</li>
</ul>

<p>More information can be found in the release notes for the various FreeBSD 5.<var
class="REPLACEABLE">X</var> releases, as well as the <tt
class="FILENAME">src/UPDATING</tt> file in the FreeBSD source tree. Notable changes to
the FreeBSD Ports Collection are listed in the <tt class="FILENAME">ports/UPDATING</tt>
and <tt class="FILENAME">ports/CHANGES</tt> files in the ports tree.</p>
</div>

<div class="SECT1">
<hr />
<h2 class="SECT1"><a id="UPGRADE" name="UPGRADE">5 Notes on Upgrading from FreeBSD 4.<var
class="REPLACEABLE">X</var></a></h2>

<p>For those users with existing FreeBSD systems, this section offers a few notes on
upgrading a FreeBSD 4.<var class="REPLACEABLE">X</var> system to 5.<var
class="REPLACEABLE">X</var>. 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 />
<h3 class="SECT2"><a id="AEN272" name="AEN272">5.1 Binary Upgrades</a></h3>

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

<p>As of this writing, the binary upgrade option in <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=sysinstall&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">sysinstall</span>(8)</span></a>
has not been well-tested for cross-major-version upgrades. Use of this feature is not
recommended.</p>

<p>Several changes may be of interest to those users accustomed to the FreeBSD 4.<var
class="REPLACEABLE">X</var> boot media. Installation floppies (on platforms that support
them, such as i386), are organized somewhat differently than on prior releases. On 4.<var
class="REPLACEABLE">X</var> releases, the floppy set contained a stripped-down kernel
with just enough functionality to install the system. This arrangement allowed the kernel
to fit on a single floppy disk, but it lacked the device drivers required by certain
hardware configurations. Beginning with FreeBSD 5.3-RELEASE, the installation floppies
contain a standard <var class="LITERAL">GENERIC</var> kernel segmented across multiple
disks, with a much more complete set of drivers and features. The boot loader prompts for
the insertion of additional disks as required. Users downloading floppy images (perhaps
to perform a network-based installation) should note that the floppy disk set now
includes three disks: <tt class="FILENAME">boot.flp</tt>, <tt
class="FILENAME">kern1.flp</tt>, and <tt class="FILENAME">kern2.flp</tt>.</p>

<p>The installation CDROMs for the i386 architecture now use a ``no-emulation'' boot
loader. This allows, among other things, the use of a <var class="LITERAL">GENERIC</var>
kernel, rather than the stripped-down kernels used on the floppy images in previous
versions. Generally, any system capable of booting the <span
class="TRADEMARK">Microsoft</span> <span
class="TRADEMARK">Windows&nbsp;NT</span>&reg;&nbsp;4, <span
class="TRADEMARK">Windows</span>&nbsp;2000, or <span
class="TRADEMARK">Windows</span>&nbsp;XP installation CDROMs should be able to boot the
FreeBSD 5.<var class="REPLACEABLE">X</var> CDROMs.</p>
</div>

<div class="SECT2">
<hr />
<h3 class="SECT2"><a id="AEN295" name="AEN295">5.2 Source Upgrades</a></h3>

<div class="NOTE">
<blockquote class="NOTE">
<p><b>Note:</b> Many users and developers have found it easier to backup all their data
and configuration files (a wise precaution in any case), perform a binary installation
(such as from CDROM), and restore their data. Compared to a source upgrade, the binary
upgrade removes the need to deal with leftover files and programs on the disk, and allows
the system to take advantage of new file system features such as the UFS2 file system
layout.</p>

<p>Users unfamiliar with the <var class="LITERAL">buildworld</var>/<var
class="LITERAL">installworld</var> procedures for updating FreeBSD from source should
<span class="emphasis"><i class="EMPHASIS">not</i></span> attempt a source upgrade, but
should instead perform a binary installation after backing up all data.</p>
</blockquote>
</div>

<p>A source-based upgrade procedure builds and installs a set of binaries compiled from
source on the local machine. It is based on the <var
class="LITERAL">buildworld</var>/<var class="LITERAL">installworld</var> procedure often
used by advanced FreeBSD users to track changes along a development branch (such as
FreeBSD-STABLE or FreeBSD-CURRENT). In general, this procedure involves more effort than
the binary upgrade procedure, but may be useful when a system's configuration files are
complex or have been highly customized. A source upgrade can also be useful for a remote
system where an administrator has remote console access but no physical access (and
therefore cannot insert installation media).</p>

<p>Reading <tt class="FILENAME">src/UPDATING</tt> is absolutely essential. The section
entitled ``To upgrade in-place from 4.x-stable to current'' contains a step-by-step
update procedure, which must be followed exactly, without making use of the ``shortcuts''
that some users occasionally employ. An annotated list of these steps is presented
below:</p>

<ol type="1">
<li>
<p>Make backups.</p>

<p>The importance of this step cannot be overstated. It is important to make backups of
all user data and configuration files. Level zero dumps with <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=dump&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">dump</span>(8)</span></a> are an
excellent way to do this, although there are of course many workable alternatives.</p>
</li>

<li>
<p>Ensure that there is about 30MB of free disk space on the <tt class="FILENAME">/</tt>
file system.</p>

<p>FreeBSD 5.<var class="REPLACEABLE">X</var> uses more space than FreeBSD 4.<var
class="REPLACEABLE">X</var>. If the <tt class="FILENAME">/tmp</tt> directory resides on
the <tt class="FILENAME">/</tt> file system (as is frequently the case), deleting all of
the content from this directory may help to free up needed space.</p>
</li>

<li>
<p>Fix <tt class="FILENAME">/etc/fstab</tt> if required.</p>

<p>This item probably only affects older FreeBSD/i386 systems. On systems that use
MBR-style disk slices, FreeBSD used to support ``compatibility slices'', where disk
partition names could take the form <tt class="FILENAME">/dev/ad0a</tt> (without
specifying a slice name explicitly). These are no longer supported; disk partitions must
be named according to the form <tt class="FILENAME">/dev/ad0s1a</tt>. In other words,
disk partitions must now completely specify a disk device, a slice number, and a
partition letter.</p>

<p>Note that ``compatibility slices'' have generally not been used by default since
FreeBSD 2.2.6-RELEASE. This item does not apply to FreeBSD/alpha at all, or to systems
using ``dangerously dediated'' mode.</p>
</li>

<li>
<p>Using <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=cvs&sektion=1&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">cvs</span>(1)</span></a> or other
means, obtain a copy of the FreeBSD base system sources (the <tt
class="FILENAME">src/</tt> module). To check out 5.3-RELEASE from the FreeBSD CVS
repository, use the <var class="LITERAL">RELENG_5_3_0_RELEASE</var> tag. For the 5.3
release and security fix branch, use the <var class="LITERAL">RELENG_5_3</var> tag. To
track the FreeBSD 5-STABLE development branch, use the <var
class="LITERAL">RELENG_5</var> branch tag. When using CVS to check out the source tree,
it is important to pass the <var class="OPTION">-P</var> flag to CVS so that it prunes
away empty directories.</p>
</li>

<li>
<p>FreeBSD 5.<var class="REPLACEABLE">X</var> requires some new entries in the system
password and group files, corresponding to various system services. They should be
installed by running:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mergemaster -p</kbd>
</pre>

<p>This step must be performed to give some new files the correct usernames and
groupnames.</p>

<p>Note that in FreeBSD 5.<var class="REPLACEABLE">X</var>, the location of the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=nologin&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">nologin</span>(8)</span></a>
utility has moved from <tt class="FILENAME">/sbin/nologin</tt> to <tt
class="FILENAME">/usr/sbin/nologin</tt>. Because a number of pseudo-users have <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=nologin&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">nologin</span>(8)</span></a> as
their login shell, this change generates additional differences in <tt
class="FILENAME">/etc/passwd</tt>.</p>
</li>

<li>
<p>Build the new userland using:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cd /usr/src</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">make buildworld</kbd>
</pre>

<p>If <var class="VARNAME">CPUTYPE</var> is defined in <tt
class="FILENAME">/etc/make.conf</tt>, it should be defined using the <var
class="LITERAL">?=</var> operator, so the <var class="LITERAL">buildworld</var> process
can override this variable if necessary.</p>

<p>Note that the <var class="VARNAME">MAKEOBJDIRPREFIX</var> must <span
class="emphasis"><i class="EMPHASIS">not</i></span> be defined in <tt
class="FILENAME">/etc/make.conf</tt>.</p>

<p>In general, most of the build ``knobs'' defined in <tt
class="FILENAME">/etc/make.conf</tt> should be commented out or removed. This statement
especially applies to those that directly affect the build or basic operation of FreeBSD,
such as <var class="VARNAME">NO_TOOLCHAIN</var>.</p>
</li>

<li>
<p>Build and install a new kernel using:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">make buildkernel</kbd>
</pre>

<p>Note that the <var class="LITERAL">buildkernel</var> <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=make&sektion=1&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">make</span>(1)</span></a> target
must be used in order to ensure that the resulting kernel is compiled with the toolchain
built in the <var class="LITERAL">buildworld</var> step above. Manually using <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=config&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">config</span>(8)</span></a> to set
up a kernel build area and attempting to build a kernel will not work.</p>

<p>Although building (and later installing) a custom kernel at this point is feasible,
upgrading using the <var class="LITERAL">GENERIC</var> kernel and installing a custom
kernel configuration later may be less error-prone. When trying to build a custom kernel
for the first time, using the <var class="LITERAL">GENERIC</var> kernel from FreeBSD
5.<var class="REPLACEABLE">X</var> as a template is highly recommended, due to the number
of device and options that have been added or changed since 4.<var
class="REPLACEABLE">X</var>. In any case, including the <var
class="LITERAL">COMPAT_FREEBSD4</var> kernel configuration option is crucial for a
successful upgrade.</p>
</li>

<li>
<p>Set up a device hints file for ISA devices with a variant of the following command.
Substitute the appropriate architecture name (e.g. <var class="LITERAL">i386</var>) for
<var class="REPLACEABLE">MACHINE</var>.</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cp sys/<var
class="REPLACEABLE">MACHINE</var>/conf/GENERIC.hints /boot/device.hints</kbd>
</pre>

<p>While an empty device hint file may be sufficient for modern hardware, ISA hints are
needed for systems with custom ISA non-PNP cards (with custom hints being needed), for
non-PNPBIOS systems, or for floppy disks to work correctly on PNPBIOS systems.</p>
</li>

<li>
<p>Install the new kernel with:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">make installkernel</kbd>
</pre>

<p>Note that while the FreeBSD 4.<var class="REPLACEABLE">X</var> kernel installs to <tt
class="FILENAME">/kernel</tt> by default, the FreeBSD 5.<var class="REPLACEABLE">X</var>
kernel installs to <tt class="FILENAME">/boot/kernel/kernel</tt>. Kernel modules under
4.<var class="REPLACEABLE">X</var> normally install to the <tt
class="FILENAME">/modules</tt> directory, whereas under 5.<var
class="REPLACEABLE">X</var> they install to <tt class="FILENAME">/boot/kernel</tt>.</p>
</li>

<li>
<p>Install the FreeBSD 5.<var class="REPLACEABLE">X</var> boot loader with:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cd /usr/src/sys/boot</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">make STRIP="" install</kbd>
</pre>

<p>This step, though optional, is highly recommended.</p>
</li>

<li>
<p>Disable third-party modules (such as those for VMware) to prevent crashes caused by
changes in kernel ABIs or other incompatibilities.</p>
</li>

<li>
<p>Reboot to single-user mode. Rebooting at this point is absolutely required because the
new kernel must be running to install the new userland. Being in single-user mode will
drastically decrease the potential for unexpected things to happen during the upgrade
because there will be no other programs running.</p>
</li>

<li>
<p>Mount the required file systems using:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">fsck -p</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mount -uw /</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mount -at ufs</kbd>
</pre>

<p>Note that the <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=fsck&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">fsck</span>(8)</span></a>
invocation is necessary to update certain fields in the file system superblocks for
FreeBSD 5.<var class="REPLACEABLE">X</var>. If the system clock tracks local time rather
than UTC time, also perform:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">adjkerntz -i</kbd>
</pre>

<p>During this step, the following warning message may appear on the console (numerous
times).</p>

<pre class="SCREEN">
WARNING: userland calling deprecated sysctl, please rebuild world
</pre>

<p>This message can be safely ignored.</p>
</li>

<li>
<p>Delete the C++ header files with:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">rm -rf /usr/include/g++</kbd>
</pre>

<p>This step keeps future compilations from accidentally picking up old header files from
the <b class="APPLICATION">GCC</b> 2.95 C++ compiler.</p>
</li>

<li>
<p>Install the new userland utilities with:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cd /usr/src</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">make installworld</kbd>
</pre>
</li>

<li>
<p>On systems running <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=named&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">named</span>(8)</span></a>, its
configuration files need to be moved into a <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=chroot&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">chroot</span>(8)</span></a> area
in <tt class="FILENAME">/var/named</tt>. If any files exist in <tt
class="FILENAME">/var/named</tt>, they should be backed up at this point.</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cd /etc</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mv named named.bak</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mkdir -p /var/named/etc/namedb</kbd>
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">cp -Rp named.bak/* /var/named/etc/namedb</kbd>
</pre>

<p>If the configuration uses the generated <tt class="FILENAME">localhost</tt> files, the
following steps may be needed to regenerate them:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">cd /var/named/etc/namedb</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">/bin/sh make-localhost</kbd>
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">rm -f localhost-v6.rev localhost.rev</kbd>
</pre>
</li>

<li>
<p>Update the system configuration files by running:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">mergemaster -i</kbd>
</pre>

<p>This step is non-optional. It is required to make the startup and configuration files
in <tt class="FILENAME">/etc</tt> consistent with the new kernel and world.</p>

<p>After invoking <a
href="http://www.FreeBSD.org/cgi/man.cgi?query=mergemaster&sektion=8&manpath=FreeBSD+5.3-RELEASE">
<span class="CITEREFENTRY"><span class="REFENTRYTITLE">mergemaster</span>(8)</span></a>,
it is a good idea to inspect (and possibly modify) <tt
class="FILENAME">/etc/rc.conf</tt>. A number of default values for the variables defined
in this file have changed; in particular, some services that were enabled by default in
4.<var class="REPLACEABLE">X</var> are now disabled by default in 5.<var
class="REPLACEABLE">X</var>.</p>
</li>

<li>
<p>Remove leftover <b class="APPLICATION">BIND 8</b> files:</p>

<pre class="SCREEN">
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">rm /usr/bin/dnskeygen /usr/bin/dnsquery</kbd>
<samp class="PROMPT">#</samp> <kbd class="USERINPUT">rm /usr/libexec/named-xfer</kbd>
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">rm /usr/sbin/named.restart /usr/sbin/ndc</kbd>
<samp class="PROMPT">#</samp> <kbd
class="USERINPUT">rm /usr/sbin/nslookup /usr/sbin/nsupdate</kbd>
</pre>
</li>

<li>
<p>Reboot.</p>
</li>
</ol>

<p>After upgrading the base system, upgrades to some non-base-system components are
generally needed to restore normal functionality. <b class="APPLICATION">Perl</b> is no
longer a part of the base system and should be installed from the Ports Collection
(specifically, the <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/lang/perl5.8/pkg-descr"><tt
class="FILENAME">lang/perl5.8</tt></a> port) or from a package. After this installation,
all ports and/or packages depending on <b class="APPLICATION">Perl</b> need to be
reinstalled.</p>

<p>Running FreeBSD 4.<var class="REPLACEABLE">X</var> binaries requires a set of
compatability libraries. These are available by installing the <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/misc/compat4x/pkg-descr"><tt
class="FILENAME">misc/compat4x</tt></a> package/port.</p>

<p>As mentioned in a prior section, <b class="APPLICATION">Xorg</b> is the default
implementation of the X Window System. The Ports Collection (as well as packages) rely on
this change to satisfy dependencies. To convert the installed windowing system from <b
class="APPLICATION"><span class="TRADEMARK">XFree86</span></b> to <b
class="APPLICATION">Xorg</b>, refer to the <a
href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/x-install.html"
target="_top">Installing X11</a> section in the FreeBSD Handbook.</p>
</div>
</div>

<div class="SECT1">
<hr />
<h2 class="SECT1"><a id="SUMMARY" name="SUMMARY">6 Summary</a></h2>

<p>This article presents some of the more notable new features in FreeBSD 5.<var
class="REPLACEABLE">X</var>, and lists some areas of particular concern to those users
upgrading existing FreeBSD 4.<var class="REPLACEABLE">X</var> systems. It also presents
two sets of upgrade instructions, one using binaries from installation media and one
based on recompiling the base system from source code.</p>
</div>
</div>

<h3 class="FOOTNOTES">Notes</h3>

<table border="0" class="FOOTNOTES" width="100%">
<tr>
<td align="LEFT" valign="TOP" width="5%"><a id="FTN.AEN159" name="FTN.AEN159"
href="#AEN159"><span class="footnote">[1]</span></a></td>
<td align="LEFT" valign="TOP" width="95%">
<p>Note that execution of <tt class="FILENAME">a.out</tt> executables on the i386 and
pc98 is still supported with the <var class="LITERAL">COMPAT_AOUT</var> kernel option.
Some of the compilers in the Ports Collection (for example, <a
href="http://www.FreeBSD.org/cgi/url.cgi?ports/lang/gcc28/pkg-descr"><tt
class="FILENAME">lang/gcc28</tt></a>) are still capable of generating <tt
class="FILENAME">a.out</tt> format executables.</p>
</td>
</tr>
</table>

<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>For questions about this documentation, e-mail &#60;<a
href="mailto:doc@FreeBSD.org">doc@FreeBSD.org</a>&#62;.</small></p>
++++


