Upgrading FreeBSD 2.2.x systems to 3.1 r0.1 ---------------------------------------------------------------------- Michael Smith Overview This document outlines some of the issues an administrator will encounter when upgrading a FreeBSD 2.2.x system to version 3.1. A recommended process is outlined which avoids the majority of pitfalls. Recommended Upgrade Procedure In order to avoid most of the complications involved in upgrading a 2.2.x system to 3.1, the following procedure is recommended. - Back up the following items of configuration data: System configuration from /etc, including o rc.conf o hosts o resolv.conf Installed application configurations from /usr/local/etc. Any other configuration data from user-installed applications. - Back up user data. If user data was located on the /usr partition, it is essential that this backup be verified. - Back up system logs from /var/log. - Make a record of all installed packages. Obtain a listing of all installed packages with 'pkg_info -a'. - Perform a _new_installation_, not an upgrade. During the installation, do not re-slice/repartition disks, but retain the existing disk layout. Set the 'newfs' flag to 'Yes' in the partition editor for the /, /var and /usr filesystems. Do not set the 'newfs' flag for any other filesystems, to avoid destroying user data. - Following the installation, install the packages previously recorded as being installed. If /usr/local was not located on the /usr filesystem it must be cleaned out first. - Restore user data if it was stored on the /usr filesystem. Consider moving user data _off_ this filesystem in future to ease upgrades - Merge old configuration information from saved configuration data with the new system and installed applications. This procedure cleans out as much as possible of the old operating system, reducing to a minimum the possibilities of conflicts between stale and new components. Changes Between 2.2.x and 3.1 If the user is unwilling to perform the essentially fresh install detailed above, the process becomes more complicated. Sysinstall does its best to perform the upgrade correctly, but the process is fraught with difficulties. We will discuss the changes between 2.2.x and 3.1, and detail the actual steps of the upgrade. FreeBSD 3.1 is a major upgrade from the 2.2 family. The changes most significant to the upgrade process are: - A new binary format for libraries and executables. - A new bootstrap loader for the kernel. - New device names for SCSI disks and tapes. The a.out to ELF Change In order to remain close to the leading edge of software tool development, the FreeBSD Project has adopted the ELF image format for the FreeBSD 3.x and subsequent releases. There are many sound technical reasons for this change, however it does come at a one-time cost to the system administrator upgrading from an older system. Full backwards compatability between executables has been maintained, however in order for both older (a.out) and newer (ELF) libraries and binaries to exist on the same system, the older (a.out) libraries have to be moved. The new convention is for a.out libraries to be located in a subdirectory below their original location. eg. a.out libraries that were originally located in /usr/lib are now stored in /usr/lib/aout. In order to impose this change on an installed system, libraries in their old locations must be moved to the new directories. Updating from a.out to ELF has a major impact on installed packages, and it is for this reason that the recommended upgrade procedure is to delete all installed packages and reinstall them from scratch. The package management system does not recognise the difference between an a.out and an ELF package. This can result in the situation where a newly installed package will not function because it is ELF while some of the libraries it depends on, already installed, are a.out. New Kernel Format and Bootloader In 3.1 the kernel is also an ELF executable. As such, the bootloader must also be upgraded. See the 'bootloader.txt' document for details on the new bootloader. The new bootstrap/bootloader is automatically installed by Sysinstall when upgrading. Kernel Configuration File Changes Due to significant changes in the structure of portions of the kernel, configuration files from 2.2.x systems cannot be used to build kernels under 3.1. Instead, the administrator should use the GENERIC kernel as a starting point, and use the old configuration file and the LINT kernel example as references when tuning their new kernel. Upgrading From Source The from-source upgrade path is generally recommended only for experienced administrators, and in a production environment the process should be prototyped using a scratch system before it is applied to operational systems. To perform the from-source upgrade, the system sources should be updated using whichever method is normally applied, and then 'make upgrade' should be used in place of 'make world'. This is a lengthy process, and may require some user intervention. At several stages during this upgrade, the system is in a non-bootable state, so a fixit floppy or other recovery strategy should be in place. Missing Drivers A number of drivers were declared obsolete and support was removed from FreeBSD 3.1. These include: 'ft' floppytape driver. 'aic' adaptec 151x/152x SCSI host adapter 'amd' tekram DC390 SCSI host adapter The 'aic' and 'amd' drivers may return in a later version of FreeBSD.