Knowledgebase

In this article, we will upgrade the FreeBSD operating system using freebsd-update. The freebsd-update utility can be used to update your instance with the latest patch release or you can also choose to upgrade to either a minor or major release.

Step 1: Points to consider before updating your instance

• Backup your instance. The easiest way is to take a snapshot. You can also optionally choose to have an extra backup of configuration files from /etc/.
• Reserve a maintenance period so that the upgrade can be planned and tested in that timeframe; more time should be reserved for a major release upgrade as compared to a minor or patch release upgrade.
• If you are upgrading to a major release, it safer to test the freebsd-update on a test or development instance before attempting it on a production server. You could use a snapshot to quickly fire up a test instance, test the upgrade without having any impact to your production instance.
• Before starting the upgrade, it is recommended to shutdown the services on the instance. For example: web server, database, etc. These could be enabled once the upgrade has completed. This step is especially important for major release upgrades.
• Please go through the release notes of the target FreeBSD release before you begin the upgrade.
• You need to have at least 500MB of free space in the /var partition especially for upgrading to new minor or major release.

Step 2: Updating to the latest patch release

Downloading the update

Patch releases contain fixes to operating system files and binaries and might also contain a change in the kernel. Fetch the update using freebsd-update. The output of commands below has been edited for the sake of brevity.

# freebsd-version
11.0-RELEASE-p1
# freebsd-update fetch
src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 4 mirrors found.
Fetching public key from update4.freebsd.org... done.
Fetching metadata signature for 11.0-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata files... done.
Inspecting system... done.
Preparing to download files... done.
Fetching 998 patches......... done.
Applying patches... done.
Fetching 6 files... done.
The following files will be removed as part of updating to 11.0-RELEASE-p11:
/boot/kernel/hv_ata_pci_disengage.ko
...
The following files will be added as part of updating to 11.0-RELEASE-p11:
/usr/share/zoneinfo/Asia/Barnaul
...
The following files will be updated as part of updating to 11.0-RELEASE-p11:
/bin/freebsd-version
...
WARNING: FreeBSD 11.0-RELEASE-p1 is approaching its End-of-Life date.
It is strongly recommended that you upgrade to a newer
release within the next 2 months.

Installing the update

The updates have downloaded to your server. Now install them.

# freebsd-update install
src component not installed, skipped
Installing updates... done.

Reboot into the new kernel if needed

Since updating from 11.0-RELEASE-p1 to 11.0-RELEASE-p11 involves installation of a new kernel, reboot the instance to boot into the newly installed kernel.

# shutdown -r now
... system reboot ... 
# freebsd-version
11.0-RELEASE-p11

You have now successfully upgraded your instance from 11.0-RELEASE to 11.0-RELEASE-p11. Re-enable your services and test the instance.

Step 3: Updating to a minor or major release

Downloading the upgrade

In this section, we upgrade our FreeBSD instance from FreeBSD 11.0-RELEASE to FreeBSD 11.1-RELEASE. The freebsd-update command differs in this case from the earlier patch release upgrade. Note that if there are some conflicts in files due to local changes, freebsd-update will prompt you about the same and allow you to resolve the conflict.

# freebsd-version
11.0-RELEASE-p11
# freebsd-update upgrade -r 11.1-RELEASE
src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 4 mirrors found.
Fetching metadata signature for 11.0-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata files... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/generic kernel/generic-dbg world/base world/lib32

The following components of FreeBSD do not seem to be installed:
world/base-dbg world/doc world/lib32-dbg

Does this look reasonable (y/n)? y
Fetching metadata signature for 11.1-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata files... done.
Inspecting system... done.
Fetching files from 11.0-RELEASE for merging... done.
Preparing to download files... done.
Fetching 11513 patches.....10....11510. done.
Applying patches... done.
Fetching 262 files... done.
Attempting to automatically merge changes in files... done.
The following files will be removed as part of updating to 11.1-RELEASE-p0:
/usr/include/netinet/ip_ipsec.h
...
The following files will be added as part of updating to 11.1-RELEASE-p0:
/boot/kernel/amd_ecc_inject.ko
...
The following files will be updated as part of updating to 11.1-RELEASE-p0:
/.cshrc
...
To install the downloaded upgrades, run "/usr/sbin/freebsd-update install".

Installing the upgrade

Now that the files have downloaded and all conflicts have been resolved, you can go ahead and install the update.

# freebsd-update install
src component not installed, skipped
Installing updates...
Kernel updates have been installed.  Please reboot and run
"/usr/sbin/freebsd-update install" again to finish installing updates.

Reboot into the new kernel and continue installation

Once the instance has restarted, you can confirm the version of the kernel that you are running, and resume the installation.

# uname -a
FreeBSD fbsd 11.1-RELEASE FreeBSD 11.1-RELEASE #0 r321309: Fri Jul 21 02:08:28 UTC 2017
    root@releng2.nyi.freebsd.org:/usr/obj/usr/src/sys/GENERIC  amd64
# freebsd-version
11.0-RELEASE-p11
# freebsd-update install
src component not installed, skipped
Installing updates...
Completing this upgrade requires removing old shared object files.
Please rebuild all installed 3rd party software (e.g., programs
installed from the ports tree) and then run "/usr/sbin/freebsd-update install"
again to finish installing updates.

Major versions use different Application Binary Interfaces (ABIs), which will break most third-party applications. If you use ports to build your third-party applications, you need to build all of those applications. If you use the package management system, then you can use the following command.

# pkg-static upgrade -f

Once all of the packages have been re-installed, complete the freebsd-update installation.

# freebsd-update install
src component not installed, skipped
Installing updates... done.
# freebsd-version
11.1-RELEASE

Congratulations, your instance has been upgraded to 11.1-RELEASE! Now you can proceed to enable all needed services and confirm that the instance is behaving as expected.