freebsd-skq/release/texts/UPGRADE.TXT

+=====================  Upgrading  FreeBSD  ==========================+
|                                                                     |
| 0.0        Preface                                                  |
|            0.1    DISCLAIMER                                        |
|            0.2    IMPORTANT NOTES                                   |
|                                                                     |
| 1.0        Introduction                                             |
|            1.1    Upgrade Overview                                  |
|                                                                     |
| 2.0        Procedure                                                |
|            2.1    Backup                                            |
|            2.2    Mount Filesystems                                 |
|            2.3    Select Distributions                              |
|            2.4    After Installation                                |
|                                                                     |
| 3.0        Alternative Upgrade Techniques                           |
|                                                                     |
+=====================================================================+

0.1    DISCLAIMER
---    ----------

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.

0.2    IMPORTANT NOTES
---    ---------------

These notes assume that you are using the version of sysinstall supplied
with the version of FreeBSD to which you intend to upgrade.  Using a
mismatched version of sysinstall 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
/stand/sysinstall from an existing installation to upgrade to a newer
version of FreeBSD.  This is NOT recommended.  You should instead boot
from the installation media to do an upgrade.

Furthermore, if you are upgrading from FreeBSD 2.2.5 or earlier, see
section 2.4 for important details regarding changes to the /etc/fstab
file required during the upgrade procedure.

1.0    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
document in its entirety before commencing an upgrade.  Failure to do so 
may result in a failed upgrade or loss of data.

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, adduser.conf, aliases, aliases.db, amd.map, crontab,
   csh.cshrc, csh.login, csh.logout, daily, disktab, dm.conf, exports,
   fbtab, fstab, ftpusers, gettytab, gnats, group, hosts, hosts.equiv,
   hosts.lpd, inetd.conf, kerberosIV, localtime, login.access,
   mail.rc, make.conf, manpath.config, master.passwd, mib.txt, modems,
   monthly, motd, namedb, networks, nsswitch.conf, passwd, phones,
   ppp, printcap, profile, protocols, pwd.db, rc, rc.firewall,
   rc.i386, rc.local, rc.network, rc.conf, remote, resolv.conf, rmt,
   security, sendmail.cf, services, shells, skeykeys, spwd.db,
   supfile, syslog.conf, termcap, ttys, uucp, weekly

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.

2.0    Procedure
---    ---------

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

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.

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.

2.3    Select Distributions
---    --------------------

When selecting distributions, there are no constraints on which must be
selected.  As a general rule, the 'bin' 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.

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.

Read the following, but DO NOT update /etc/fstab as described below
until the new system has booted correctly.  The upgrade procedure
replaces the previous FreeBSD kernel with a GENERIC kernel, and a custom
kernel may need to be generated to suit the local system configuration.

IMPORTANT NOTE:
==============
FreeBSD 2.2.6 introduced a change in the naming of the device from 
which the root filesystem is mounted.  This change affects all systems, 
however user intervention is only required for systems undergoing an 
upgrade installation from a version prior to FreeBSD 2.2.6.

Previously, the root filesystem was always mounted from the
compatibility slice, while other partitions on the same disk were
mounted from their true slice.  This might, for example, have resulted 
in an /etc/fstab file like:

# Device      Mountpoint      FStype  Options         Dump    Pass#
/dev/wd0s2b   none            swap    sw              0       0
/dev/wd0a     /               ufs     rw              1       1
/dev/wd0s2f   /local0         ufs     rw              1       1
/dev/wd0s2e   /usr            ufs     rw              1       1

For FreeBSD 2.2.6 and later, this format changes so that the device for 
'/' is consistent with others.  Also, the driver for the ATA-drives has
changed from wd(4) to ad(4), so the new file could look something like:

# Device      Mountpoint      FStype  Options         Dump    Pass#
/dev/ad0s2b   none            swap    sw              0       0
/dev/ad0s2a   /               ufs     rw              1       1
/dev/ad0s2f   /local0         ufs     rw              1       1
/dev/ad0s2e   /usr            ufs     rw              1       1


If /etc/fstab is not updated manually in this case, the system will
issue a warning message whenever / is mounted (normally at startup)
indicating the change that must be made.  In addition, trouble may be
experienced if the root filesystem is not correctly unmounted, whereby
the root filesystem will not be marked clean at the next reboot.

This change should be made as soon as the upgraded system has been
successfully rebooted.

3.0    Alternative Upgrade Techniques
---    ------------------------------

Those interested in an upgrade method that allows more flexibility and
sophistication should take a look at the "The Cutting Edge" chapter in the
Handbook (http://www.FreeBSD.org/docs/en/books/handbook/cutting-edge.html)
which describes how to upgrade FreeBSD from the source code.  This method
requires reliable network connectivity, extra disk space and spare time,
but has advantages for networks and other more complex installations.