Chapter 25. Updating and Upgrading FreeBSD (2023)

Timely application of security patches and upgrading to a newer version of an operating system are important aspects of ongoing system administration. FreeBSD includes a utility calledfreebsd-updatewhich can be used to accomplish both of these tasks.

This utility supports binary security and errata updates for FreeBSD without having to manually compile and install the patch or a new kernel. Binary updates are available for all architectures and versions currently supported by the security team. The list of supported versions and their estimated end-of-life dates are listed below

This utility also supports OS upgrades to minor point releases as well as upgrades to a different release branch. Before upgrading to a new release, read its release announcement as it contains important information about the release. Release announcements are available at

When aCrontab(5)Using the functions offreebsd-update(8)is present, it must be disabled before upgrading the operating system.

This section describes the configuration file used byfreebsd-update, demonstrates how to apply a security patch and upgrade to a minor or major operating system version, and discusses some of the operating system upgrade considerations.

25.2.1. The configuration file

The default configuration file forfreebsd-updateworks as is. Some users may want to customize the default configuration/etc/freebsd-update.conf, allowing better control of the process. The comments in this file explain the options available, but the following may require a bit more explanation:

# Base system components that should be kept up to date. Components world kernel

This parameter controls which parts of FreeBSD are kept up to date. By default, the entire base system and kernel is updated. Instead, individual components can be specified, e.gWhat/BasisorWhich/sysHowever, the best option is to leave this at the default, as changing it to include specific items requires all required items to be listed. Over time, this could have disastrous consequences as the source code and binaries might get out of sync.

# Paths beginning with anything that matches an entry in an IgnorePaths# directive are ignored. IgnorePaths /boot/kernel/linker.hints

To leave certain directories, e.g/Containeror/sbin, which will remain untouched during the update process, add their paths to this directive. This option can be used to preventfreebsd-updateprevent local changes from being overwritten.

# Paths beginning with anything that matches an entry in an UpdateIfUnmodified# directive are only updated if the contents of the file have not # been modified by the user (unless changes are merged; see below).UpdateIfUnmodified / etc/ /var/ / root/ /.cshrc /.profile

This option only updates unchanged configuration files in the specified directories. Any changes made by the user will prevent these files from being updated automatically. There is another optionKeepModifiedMetadata, who will teachfreebsd-updateto save the changes during the merge.

# When upgrading to a new FreeBSD release, files matching MergeChanges# have all local changes merged into the new release version. MergeChanges /etc/ /var/named/etc/ /boot/device.hints

List of directories with configuration files thatfreebsd-updateshould try to merge. The file merging process is a series ofdifference(1)patches similar toMergemaster(8), but with fewer options. Merges are either accepted, open an editor, or causefreebsd-updatecancel. If in doubt, secure/etcand just accept the merges. SeeMergemaster(8)for more information aboutMergemaster.

# Directory to store downloaded updates and temporary# files used by FreeBSD Update.# Working directory /var/db/freebsd-update
(Video) "Introduction to FreeBSD Ports - 25 years and counting" - Ben Woods (LCA 2020)

All patches and temporary files are stored in this directory. In cases where the user performs a version upgrade, this location should have at least one gigabyte of space available.

# When upgrading between releases, should the list of components # be read strictly (StrictComponents yes) or just serve as a list of components# that *might* be installed that FreeBSD Update should find out# which are actually installed and update them ( StrictComponents no)?# StrictComponents no

When this option is set toYes indeed,freebsd-updatewill assume that thecomponentsThe list is complete and does not attempt to make changes outside of the list.freebsd-updatewill attempt to update any file associated with thecomponentslist.

25.2.2. Apply security patches

The process for applying FreeBSD security patches has been simplified, allowing an administrator to keep a system fully patchedfreebsd-update.For more information on FreeBSD security advisories, seeFreeBSD Security Advisories.

FreeBSD security patches can be downloaded and installed using the following commands. The first command determines whether there are any pending patches available and, if so, lists the files that will be modified when the patches are applied. The second command applies the patches.

# get freebsd-update# Install freebsd update

If the update applies kernel patches, the system must be rebooted to boot into the patched kernel. If the patch has been applied to running binaries, the affected applications should be restarted to use the patched version of the binary.

Normally the user must be prepared to reboot the system. To know if the system needs to be rebooted due to a kernel update, run the commandsfreebsd-version -kanduname -r.Reboot the system if the outputs differ.

The system can be configured to automatically check for updates once a day by adding this entry to/etc/crontab:

@daily root freebsd-update cron

If there are patches, they will be automatically downloaded but not appliedrootThe user will receive an email so that the patches can be checked and installed manuallyInstall freebsd update.

if something goes wrongfreebsd-updatehas the option to undo recent changes with the following command:

# Freebsd-Update-RollbackUninstall updates...done.

Again, if the kernel or kernel modules have been modified, the system should be rebooted and any affected binaries should be rebooted.

Only theGENERICKernel can be updated automaticallyfreebsd-update.If a custom kernel is installed, it must be rebuilt and then reinstalledfreebsd-updatefinish installing the updates. The default kernel name isGENERIC.ThatName(1)command can be used to verify its installation.

Always keep a copyGENERICcore inside/boot/GENERAL.It is helpful in diagnosing a variety of problems and performing version upgradesCustom kernels with FreeBSD 9.X and laterfor instructions on how to obtain a copy of theGENERICKernel.

(Video) BSD Synergy Episode 25: Getting Started with Bhyve

Unless the default configuration in/etc/freebsd-update.confwas changed,freebsd-updateinstalls the updated kernel sources along with the rest of the updates. Rebuilding and reinstalling a new custom kernel can then be done in the usual way.

The updates distributed byfreebsd-updatedon't always involve the kernel. There is no need to rebuild a custom kernel if the kernel sources have not been modified byInstall freebsd update.However,freebsd-updateis always updated/usr/src/sys/conf/ current patch level, as indicated by-pNumber reported byuname -r, is obtained from this file. Rebuilding a custom kernel even if nothing else has changed makes it possibleyour nameto accurately report the current patch level of the system. This is particularly useful when maintaining multiple systems, as it allows for a quick assessment of the updates installed on each system.

25.2.3. Perform major and minor version upgrades

Upgrades from one minor release of FreeBSD to another, such as from FreeBSD 9.0 to FreeBSD 9.1, are invokedminor versionUpgrades.major versionUpgrades occur when FreeBSD is upgraded from one major release to another, e.g. B. From FreeBSD 9.X to FreeBSD 10.X. Both types of upgrades can be performed through deploymentfreebsd-updatewith a release version target.

If the system is running a custom kernel, make sure you have a copy of theGENERICkernel exists in/boot/GENERALbefore you start the upgrade. Please referCustom kernels with FreeBSD 9.X and laterfor instructions on how to obtain a copy of theGENERICKernel.

Running the following command on a FreeBSD 9.0 system will upgrade it to FreeBSD 9.1:

# freebsd-update -r 9.1-RELEASE-Upgrade

After the command is received,freebsd-updateevaluates the configuration file and the current system to gather the information needed to complete the upgrade. An on-screen list shows which components have been recognized and which have not. Example:

Looking up mirrors... 1 mirrors found. Metadata signature is retrievedPro9.0 RELEASE from metadata index...done.check system...done.The following FreeBSD components appear to be installed: kernel/smp src/base src/bin src/contrib src/crypto src/etc src/gamessrc/gnu src/include src/krb5 src/lib src/libexec src/release src/ rescuesrc/sbin src/secure src/share src/sys src/tools src/ubin src/usbinworld/base world/info world/lib32 world/manpagesThe following components of FreeBSDagaindoesn't appear to be installed: kernel/generic world/catpages world/dict world/doc world/gamesworld/proflibs That looks reasonable(i/n)? j

At this point,freebsd-updatewill attempt to download any files required for the upgrade. In some cases, the user may be asked questions about what to install or how to proceed.

If you are using a custom kernel, the above step will produce a warning similar to the following:

WARNING: This system runs a"MYKERNEL"Kernel that is not a kernel configuration distributed as part of FreeBSD 9.0-RELEASE. This kernel is not updated: you MUST manually update the kernel before running it"Install /usr/sbin/freebsd-update"

This warning can safely be ignored at this pointGENERICKernel is used as an intermediate step in the upgrade process.

Once all patches have been downloaded to the local system, they will be applied. This process may take a while depending on the speed and load of the computer. The configuration files are then merged. The merging process requires some user intervention as the file can be merged or an editor can appear on screen for a manual merge. The results of each successful merge are displayed to the user as the process continues. A failed or ignored merge will abort the process of backing up/etcand manually merge important files such asmaster.passwdorgroupat a later time.

The system will not be changed yet as all patching and merging will take place in a different directory. Once all the patches have been successfully applied, all the configuration files have been merged and it seems like the process is going smoothly, the changes can be pushed to the user's hard drive with the following command:

# Install freebsd update

The kernel and kernel modules are patched first. If the system is running a custom kernel, usenextboot(8)to set the kernel to the updated one for the next boot/boot/GENERAL:

# nextboot -k GENERAL
(Video) [2022] Getting Started With FreeBSD, Part 1 - A little History, Download & Install

Before rebooting with theGENERICKernel, make sure it contains all the drivers needed for the system to boot properly and connect to the network when the machine to be updated is accessed remotely. In particular, if the running custom kernel contains built-in functions that are normally provided by kernel modules, make sure to temporarily load those modules into theGENERICkernel with the/boot/loader.confIt is recommended to disable non-essential services and all disk and network mounts until the upgrade process is complete.

The machine should now reboot with the updated kernel:

# shut down now -r

Once the system is back online, restart itfreebsd-updatewith the following command. Since the state of the process has been saved,freebsd-updatedoes not start over, but instead proceeds to the next phase and removes all old shared libraries and object files.

# Install freebsd update

Depending on whether library version numbers have been incremented, there may only be two installation phases instead of three.

The upgrade is now complete. If it was a major version upgrade, reinstall all ports and packages as described inUpdating packages after a major version upgrade. Custom kernels with FreeBSD 9.X and later

Before usefreebsd-update, make sure you have a copy of theGENERICkernel exists in/boot/GENERAL.If a custom kernel is built only once, the kernel will be in/boot/kernel.oldis theGENERICkernel. Just rename this directory to/boot/GENERAL.

If a custom kernel has been built more than once, or if you do not know how many times the custom kernel has been built, obtain a copy of theGENERICKernel corresponding to the current version of the operating system. If physical access to the system is possible, a copy of theGENERICKernel can be installed from installation media:

# mount /cdrom# cd /cdrom/usr/freebsd-dist# tar -C/ -xvf kernel.txz boot/kernel/kernel

Alternatively theGENERICThe kernel can be rebuilt and installed from sources:

# cd /usr/src# Kernel erstellen __MAKE_CONF=/dev/null SRCCONF=/dev/null

So that this kernel can be identified asGENERICkernel throughfreebsd-update,theGENERICConfiguration file must not have been modified in any way. It is also recommended to build the kernel without any other special options.

reboot into theGENERICKernel is not required sincefreebsd-updateonly needs/boot/GENERALexist. Updating packages after a major version upgrade

In general, installed applications continue to work fine after minor version upgrades. Major versions use different Application Binary Interfaces (ABIs) which break most third-party applications. After upgrading from major versions, all installed packages and ports must be upgraded. Packages can be upgraded withpkg-Upgrade.To update installed ports use a utility such asports-mgmt/portmaster.

A forced upgrade of all installed packages replaces the packages with new versions from the repository even if the version number has not increased. This is required because of ABI version switching when upgrading between major releases of FreeBSD. The forced upgrade can be performed by performing:

# pkg static upgrade -f

A rebuild of all installed applications can be performed with this command:

# Harbormaster -off

This command displays the configuration screens for each application with configurable options and waits for the user to interact with those screens. To prevent this behavior and only use the default options, use include-Gin the above command.

Once the software upgrades are complete, complete the upgrade process with a final call tofreebsd-updateto tie up any loose ends in the upgrade process:

# Install freebsd update

If theGENERICkernel has been used temporarily, it is time to build and install a new custom kernel using the instructions inConfiguring the FreeBSD kernel.

Reboot into the new FreeBSD version. The upgrade process is now complete.

(Video) FreeBSD 13 .1 Build From Source ( Highlights )

25.2.4. system status comparison

The health of the installed FreeBSD version against a known good copy can be tested withfreebsd-update IDS.This command evaluates the current version of system utilities, libraries and configuration files and can be used as an integrated intrusion detection system (IDS).

This command is not a substitute for a real IDS such assecurity/breezing.Iffreebsd-updatesaves data to disk, the possibility of manipulation is obvious. However, this possibility can be restricted by usekern.secureleveland by saving thefreebsd-updateData on a read-only file system when not in use, a better solution would be to compare the system to a secure disk such as a disk. B. a DVD or a securely stored external USB hard disk device. in utility is described inBinary Verification

To start the comparison, specify the output file to save the results to:

# freebsd-update IDS >> outfile.ids

The system will now be checked and a long list of files along with the SHA256 hash values ​​for both the known value in the version and the current installation will be sent to the specified output file.

The entries in the listing are extremely long, but the output format can be easily analyzed. For example, to get a list of all files that differ from those in version, enter the following command:

(Video) FreeBSD 12 2 Review - As Good as Ever!

# cat outfile.ids | awk '{ print $1 }' | more/etc/master.passwd/etc/motd/etc/passwd/etc/pf.conf

This sample output has been truncated because there are many more files. Some files show natural changes. Example:/etc/passwordwill be changed when users are added to the system. Kernel modules can differ as followsfreebsd-updatemay have updated. To exclude specific files or directories, add them to theIDSIgnorePathspossibility one/etc/freebsd-update.conf.


1. A Clueless & Intoxicated Free BSD Install Guide // 25 Days of... Not Just Linux Anymore
2. TECKNET 1080p HD Streaming Webcam on FreeBSD - Unbox, Config and test
3. FreeBSD - Virtualization - bhyve and vm-bhyve setup
(Marko Tasic)
4. A Look and brief introduction to FreeBSD 12.1
(DJ Ware)
5. Update: ADDS Regent 25 Serial Terminal Restoration, IT WORKS! mostly!! :o)
6. Replacing an Oracle Server with FreeBSD, OpenZFS, and PostgreSQL (2019)
(vBSDcon Videos)
Top Articles
Latest Posts
Article information

Author: Greg O'Connell

Last Updated: 29/06/2023

Views: 6333

Rating: 4.1 / 5 (42 voted)

Reviews: 89% of readers found this page helpful

Author information

Name: Greg O'Connell

Birthday: 1992-01-10

Address: Suite 517 2436 Jefferey Pass, Shanitaside, UT 27519

Phone: +2614651609714

Job: Education Developer

Hobby: Cooking, Gambling, Pottery, Shooting, Baseball, Singing, Snowboarding

Introduction: My name is Greg O'Connell, I am a delightful, colorful, talented, kind, lively, modern, tender person who loves writing and wants to share my knowledge and understanding with you.