3 Upgrading FreeBSD

These instructions describe a procedure for doing a binary upgrade from an older version of FreeBSD.

Warning: While the FreeBSD upgrade procedure does its best to safeguard against accidental loss of data, it is still more than possible to wipe out your entire disk with this installation! Please do not accept the final confirmation request unless you have adequately backed up any important data files.

Important: These notes assume that you are using the version of sysinstall(8) supplied with the version of FreeBSD to which you intend to upgrade. Using a mismatched version of sysinstall(8) is almost guaranteed to cause problems and has been known to leave systems in an unusable state. The most commonly made mistake in this regard is the use of an old copy of sysinstall(8) from an existing installation to upgrade to a newer version of FreeBSD. This is not recommended.

Warning: Binary upgrades to FreeBSD 6.4-STABLE from FreeBSD 4-STABLE are not supported at this time. There are some files present in a FreeBSD 4-STABLE whose presence can be disruptive, but are not removed by a binary upgrade. One notable example is that an old /usr/include/g++ directory will cause C++ programs to compile incorrectly (or not at all).

These upgrade instructions are provided for the use of users upgrading from relatively recent FreeBSD 6-STABLE snapshots.

3.1 Introduction

The upgrade procedure replaces distributions selected by the user with those corresponding to the new FreeBSD release. It preserves standard system configuration data, as well as user data, installed packages and other software.

Administrators contemplating an upgrade are encouraged to study this section in its entirety before commencing an upgrade. Failure to do so may result in a failed upgrade or loss of data.

3.1.1 Upgrade Overview

Upgrading of a distribution is performed by extracting the new version of the component over the top of the previous version. Files belonging to the old distribution are not deleted.

System configuration is preserved by retaining and restoring the previous version of the following files:

Xaccel.ini, XF86Config, adduser.conf, aliases, aliases.db, amd.map, crontab, csh.cshrc, csh.login, csh.logout, cvsupfile, dhclient.conf, disktab, dm.conf, dumpdates, exports, fbtab, fstab, ftpusers, gettytab, gnats, group, hosts, hosts.allow, hosts.equiv, hosts.lpd, inetd.conf, localtime, login.access, login.conf, mail, mail.rc, make.conf, manpath.config, master.passwd, motd, namedb, networks, newsyslog.conf, nsmb.conf, nsswitch.conf, pam.conf, passwd, periodic, ppp, printcap, profile, pwd.db, rc.conf, rc.conf.local, rc.firewall, rc.local, remote, resolv.conf, rmt, sendmail.cf, sendmail.cw, services, shells, skeykeys, spwd.db, ssh, syslog.conf, ttys, uucp

The versions of these files which correspond to the new version are moved to /etc/upgrade/. The system administrator may peruse these new versions and merge components as desired. Note that many of these files are interdependent, and the best merge procedure is to copy all site-specific data from the current files into the new.

During the upgrade procedure, the administrator is prompted for a location into which all files from /etc/ are saved. In the event that local modifications have been made to other files, they may be subsequently retrieved from this location.

3.2 Procedure

This section details the upgrade procedure. Particular attention is given to items which substantially differ from a normal installation.

3.2.1 Backup

User data and system configuration should be backed up before upgrading. While the upgrade procedure does its best to prevent accidental mistakes, it is possible to partially or completely destroy data and configuration information.

3.2.2 Mount Filesystems

The disklabel editor is entered with the nominated disk's filesystem devices listed. Prior to commencing the upgrade, the administrator should make a note of the device names and corresponding mountpoints. These mountpoints should be entered here. Do not set the “newfs flag” for any filesystems, as this will cause data loss.

3.2.3 Select Distributions

When selecting distributions, there are no constraints on which must be selected. As a general rule, the base distribution should be selected for an update, and the man distribution if manpages are already installed. Other distributions may be selected beyond those originally installed if the administrator wishes to add additional functionality.

3.2.4 After Installation

Once the installation procedure has completed, the administrator is prompted to examine the new configuration files. At this point, checks should be made to ensure that the system configuration is valid. In particular, the /etc/rc.conf and /etc/fstab files should be checked.

3.3 Upgrading from Source Code

Those interested in an upgrade method that allows more flexibility and sophistication should take a look at The Cutting Edge in the FreeBSD Handbook. This procedure involves rebuilding all of FreeBSD from source code. It requires reliable network connectivity, extra disk space, and time, but has advantages for networks and other more complex installations. This is roughly the same procedure as is used for track the -STABLE or -CURRENT development branches.

/usr/src/UPDATING contains important information on updating a FreeBSD system from source code. It lists various issues resulting from changes in FreeBSD that may affect an upgrade.

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

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

All users of FreeBSD 6-STABLE should subscribe to the <stable@FreeBSD.org> mailing list.

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