How to Update and Upgrade FreeBSD?

Published on: January 7, 1970

.

19 min read

.

For German Version

FreeBSD is under ongoing development between releases. Others like to stay up with the most recent advancements, while others prefer to utilize the officially published versions. However, even official versions are often updated with vital security and other patches. FreeBSD offers all the required tools to maintain the system up-to-date and facilitates upgrades between versions, regardless of the installed version. This tutorial shows how to monitor the development system and the fundamental tools for maintaining an up-to-date FreeBSD system.

After completing this tutorial, you will understand:

• How to maintain an up-to-date FreeBSD system with freebsd-update or Git.

• How to compare the installed state of a system to a known pristine copy.

• How to use Git or documentation ports to keep the installed documentation current.

• The distinction between the FreeBSD-STABLE and FreeBSD-CURRENT development branches.

• How to replace and rebuild the complete operating system.

How to Update FreeBSD?

Important components of continuous system management include applying security updates in a timely manner and upgrading to a newer version of an operating system. The FreeBSD program freebsd-update is used to do both of these operations.

The freebsd-update utility is used to fetch, install, and roll back binary updates to the FreeBSD core operating system. This program allows binary security and errata updates to FreeBSD, eliminating the need to create and install a patch or a new kernel manually. Please note that updates are available if they are being constructed for the FreeBSD release and architecture that is currently in use. the FreeBSD Security Team primarily develops upgrades for binary releases released by the FreeBSD Release Engineering Team, e.g. FreeBSD 11.2-RELEASE and 12.0-RELEASE, but not FreeBSD

FreeBSD 11.2-STABLE or 13.0-CURRENT. The security team supports all architectures and versions for which binary updates are available. The supported release list and expected end-of-life dates are found at https://www.FreeBSD.org/security/.

This application allows operating system upgrades to minor point releases and upgrades to a different release branch. Review the release announcement before upgrading to a new version, since it provides critical information about the release. Release notices may be found at https://www.FreeBSD.org/releases/.

The stable branch of each major FreeBSD version is officially maintained for five years, but individual point releases are only supported for three months following the next point release. At the time of writing, supported FreeBSD releases are given below:

Branch	Release	Release Date	Expected EoL
stable/13	n/a	n/a	January 31, 2026
releng/13.1	13.1-RELEASE	May 16, 2022	13.2-RELEASE + 3 months
stable/12	n/a	n/a	December 31, 2023
releng/12.3	12.3-RELEASE	December 7, 2021	12.4-RELEASE + 3 months
releng/12.4	12.4-RELEASE	December 5, 2022	December 31, 2023

Table 1. Supported FreeBSD releases

Future FreeBSD release schedules are given below. Please, note that release dates are estimated and subject to change.

Date	Event
March 2023	FreeBSD 13.2
July 2023	FreeBSD 14.0

Table 2. Upcoming FreeBSD Release Dates

This section details the configuration file used by freebsd-update, illustrates how to deploy a security patch and upgrade to a minor or major operating system version, and addresses some upgrade concerns.

How to Maintain Configuration File?

The default configuration file for freebsd-update is fully operational. Some users may desire to modify the default setting in /etc/freebsd-update.conf to improve process management. This file's comments clarify the possible choices, however, the following may need more clarification.

• The following setting determines which components of FreeBSD will be kept current. By default, the complete base system and kernel are updated. Individual components, such as src/base or src/sys, might be supplied instead. However, it is preferable to keep this as it is since modifying it to include certain objects necessitates listing each item. This might have severe repercussions over time, since source code and binary files may fall out of sync.

# Components of the base system which should be kept updated.
Components world kernel

• To exclude certain folders from the update process, such as /bin or /sbin, add their paths to the following setting. This option may be used to prevent local changes from being overwritten by freebsd-update.

# Paths which start with anything matching an entry in an IgnorePaths
# statement will be ignored.
IgnorePaths /boot/kernel/linker.hints

• Next option will only update configuration files that have not been updated in the given folders. Any modifications made by the user will prevent these files from being automatically updated. KeepModifiedMetadata is an alternative option that instructs freebsd-update to save modifications during the merging.

# Paths which start with anything matching an entry in an UpdateIfUnmodified
# statement will only be 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

• List of folders containing configuration files that should be merged by freebsd-update. Similar to mergemaster, but with fewer settings, the file merge process is a sequence of diff patches. Merges are either accepted, an editor is opened, or freebsd-update is terminated. When uncertain, back up /etc and accept merges.

# When upgrading to a new FreeBSD release, files that match MergeChanges
# will have any local changes merged into the version from the new release.
MergeChanges /etc/ /var/named/etc/ /boot/device.hints

• The following WorkDir directory contains all patch files and temporary files. If the user is doing a version upgrade, this location should have at least 1 GB of free storage space.

# Directory in which to store downloaded updates and temporary
# files used by FreeBSD Update.
# WorkDir /var/db/freebsd-update

• When the next option is enabled by setting to yes, freebsd-update will presume that the Components list is exhaustive and will not try to make any modifications outside of the list. freebsd-update will try to update each file in the Components list.

# When upgrading between releases, should the list of Components be
# read strictly (StrictComponents yes) or merely as a list of components
# which *might* be installed of which FreeBSD Update should figure out
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no

How to Apply Security Patches?

The process of deploying FreeBSD security updates has been streamlined, enabling an administrator to maintain a fully patched system using freebsd-update.

You may download and install FreeBSD security fixes using the following instructions. The first command determines whether there are any pending patches and, if so, lists the files that will be modified if the patches are applied. The second command applies the necessary fixes.

freebsd-update fetch
freebsd-update install

If the update adds kernel patches, the system must be rebooted for the patched kernel to load. If the patch was deployed to any running binaries, the affected apps must be restarted so that the patched binary is used.

Typically, the user must be ready to restart the machine. To determine whether a kernel upgrade requires a system reboot, execute the following commands. If the results vary, reboot the machine.

freebsd-version -k
uname -r

By adding the following item to /etc/crontab, the machine may be set to check for updates automatically once per day:

@daily root freebsd-update cron

If patches exist, they will be downloaded automatically but not applied. The root user will get an email to evaluate and manually apply the fixes using freebsd-update install.

Using the following command, freebsd-update may revert the previous set of modifications if anything goes wrong.

freebsd-update rollback

If the kernel or any kernel modules were updated, the system must be restarted, and any impacted binaries must also be restarted.

freebsd-update can only automatically update the GENERIC kernel. If a custom kernel is installed, it must be rebuilt and reinstalled once freebsd-update has completed installing the updates. The default kernel name is GENERIC. The uname command is used to confirm the system's installation.

tip

Maintain a copy of the GENERIC kernel in /boot/GENERIC at all times. It aids in the diagnosis of a number of issues and the implementation of version updates.

freebsd-update installs the new kernel sources together with the other updates unless the default setting in /etc/freebsd-update.conf has been modified. The rebuilding and reinstallation of a new custom kernel then proceed as normal.

Not all of the updates sent by freebsd-update include the kernel. It is not essential to create a custom kernel if freebsd-update install has not modified the kernel sources. freebsd-update, however, always updates /usr/src/sys/conf/newvers.sh. This file provides the current patch level, as indicated by the -p number returned by uname -r. Rebuilding a custom kernel enables uname to correctly display the current patch level of the system, even if nothing else has changed. This is especially useful when servicing many systems since it enables a fast evaluation of the updates put on each.

How to Perform Major and Minor Version Upgrades?

Upgrades from one minor version of FreeBSD to the next, such as from 13.0 to 13.1, are referred to as "minor version upgrades." When FreeBSD is updated from one major version to another, such as from FreeBSD 12.X to FreeBSD 13.X, major version upgrades occur. Both forms of upgrades are possible when freebsd-update is provided with a release version target.

Before beginning the upgrade, if the system is running a custom kernel, ensure that a copy of the GENERIC kernel exists in /boot/GENERIC.

When executed on a FreeBSD 13.0 machine, the following command will update it to FreeBSD 13.1:

freebsd-update -r 13.1-RELEASE upgrade

After receiving the command, freebsd-update will assess the configuration file and current system in an effort to obtain the required information to complete the upgrade. A screen listing similar to the one given below will indicate which components have been discovered and which have not:

Looking up update.FreeBSD.org mirrors... 1 mirrors found.
Fetching metadata signature for 13.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.
  
The following components of FreeBSD seem to be installed:
kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
world/base world/info world/lib32 world/manpages

The following components of FreeBSD do not seem to be installed:
kernel/generic world/catpages world/dict world/doc world/games
world/proflibs
  
Does this look reasonable (y/n)? y

Press y to proceed with the update. At this time, freebsd-update will endeavor to download all upgrade-required files. In some circumstances, the user may be asked what to install or how to continue.

When running a modified kernel, the above procedure will generate a warning similar to the one below:

WARNING: This system is running a "MyCustomKernel" kernel, which is not a
kernel configuration distributed as part of FreeBSD 13.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"

At this time, it is safe to disregard this warning. As part of the upgrading procedure, the new GENERIC kernel will be used.

Once all patches have been successfully downloaded to the local system, they will be implemented. This procedure takes some time, depending on the machine's speed and workload. Afterward, configuration files are combined. As a file may be merged or an editor may appear on-screen for a manual merge, the merging process involves some user interaction. As the process progresses, the user will see the outcomes of each successful merging. A failed or disregarded merging will result in the termination of the procedure. Users desire to create a backup of /etc and manually combine crucial files, such as master.password and group, at a later time.

The system has not yet been modified, since all patching and merging are occurring in a separate location. Once all patches have been successfully applied, all configuration files have been merged, and the process seems to be proceeding well, the user may commit the changes to the disk using the following command.

freebsd-update install

First, the kernel and kernel modules will be modified. If the system is currently operating with a custom kernel, nextboot is used to set the kernel for the next boot to the modified /boot/GENERIC by running the next command:

nextboot -k GENERIC

warning

Before restarting with the GENERIC kernel, ensure that it has all the drivers necessary for the system to boot and connect to the network if the computer being upgraded is remotely accessible. Specifically, if the running custom kernel includes functionality that is typically supplied by kernel modules, load these modules temporarily into the GENERIC kernel using the /boot/loader.conf facility. It is advised to deactivate all non-essential services including disk and network mounts until the update is complete.

Your FreeBSD system must now be rebooted for the upgraded kernel to take effect by running the next command:

shutdown -r now

Once the system is back up, use the following command to restart freebsd-update: Since the status of the process has been preserved, freebsd-update will not restart from the beginning; instead, it will delete all old shared libraries and object files during the next phase.

freebsd-update install

Depending on whether or not library version numbers were increased, there may only be two install steps as opposed to three.

The upgrade is now complete. Reinstall all ports and packages as stated in Upgrading Packages After a Major Version Update if this was a major version upgrade.

How to Update Custom Kernels for FreeBSD versions 9.x and later?

You may update your FreeBSD server when you have customized the kernel by following the steps listed below:

1. Before running freebsd-update, check that /boot/GENERIC has a copy of the GENERIC kernel. /boot/kernel.old contains the GENERIC kernel if a custom kernel has only been generated once. Simply change the directory's name to /boot/GENERIC.

2. If a custom kernel has been generated several times or if the number of times is unknown, get a copy of the GENERIC kernel that corresponds to the current version of the operating system. If physical access to the machine is available, it is possible to install a copy of the GENERIC kernel from the installation media by running the next commands:

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

3. Optionally, the GENERIC kernel may be recompiled and installed from the source by running the following commands:

cd /usr/src
make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null

For freebsd-update to recognize this kernel as the GENERIC kernel, the GENERIC configuration file must not have been updated in any manner. Additionally, it is preferred that the kernel be compiled without any additional special parameters.

It is not necessary to reboot into the GENERIC kernel since freebsd-update simply requires /boot/GENERIC to exist.

How to Upgrade Packages After a Major Version Upgrade?

In general, installed apps will continue to function normally after minor version updates. Major versions use various Application Binary Interfaces (ABIs), which cause the majority of third-party programs to fail. After an update to a major version, all installed packages and ports must be upgraded. Packages may be updated with pkg upgrade. You may utilize ports-mgmt/portmaster tool to update installed ports.

Even though the version number has not changed, a forced upgrade of all installed packages will replace the packages with new ones from the repository. This is necessary due to the ABI version change when upgrading between major FreeBSD versions. The forced update may be implemented by running the next command:

pkg-static upgrade -f

A rebuild of all installed applications may be accomplished with the following command:

portmaster -af

This command displays setup panels for each program with customizable settings and waits for user interaction. Include -G in the preceding command to avoid this behavior and use the default parameters.

Once the software updates are complete, conclude the upgrading process with the last call to freebsd-update to tie up any remaining loose ends:

freebsd-update install

If the GENERIC kernel was used temporarily, now is the time to develop and install a new custom kernel.

Reboot the system to the latest version of FreeBSD. The process of upgrading is now complete.

How to Test System State?

Using freebsd-update IDS, it is possible to compare the installed FreeBSD version to a known-good copy. This command may be used as a built-in Intrusion Detection System (IDS) since it analyzes the current version of system utilities, libraries, and configuration files.

warning

This command is not a substitute for a true intrusion detection system, such as security/snort. As freebsd-update maintains data on disk, manipulation is a distinct possibility. A preferable option would be to compare the system against a secure disk, such as a DVD or securely stored external USB disk device. Binary Verification describes an alternate way of delivering IDS capabilities using a built-in tool.

1. To start the comparison, indicate the output file where the results will be saved by running the next command:

freebsd-update IDS >> outfile.ids

A detailed listing of files, together with the SHA256 hash values for both the known value in the release and the current installation, will be provided to the output file chosen. The listing's entries are exceedingly lengthy, yet the output format is readily parsable.

2. Execute the following command, for example, to acquire a list of all files that vary from those in the release:

cat outfile.ids | awk '{ print $1 }' | more

You may see the output similar to the below:

/etc/master.passwd
/etc/motd
/etc/passwd
/etc/pf.conf

Modifications of some files are normal. For instance, /etc/passwd is modified when users have been added to the system. Kernel modules differ when freebsd-update updates them. To exclude specific files or directories, add them to the IDSIgnorePaths option in /etc/freebsd-update.conf.

How to Update Documentation Collection?

FreeBSD's documentation is a fundamental component of the operating system. While the FreeBSD documentation is always accessible on the FreeBSD website, it might be useful to have a local copy of the website, handbooks, FAQ, and articles.

Rebuilding the FreeBSD documentation from the source needs a set of tools that are not included in the FreeBSD core system. Following these instructions from the FreeBSD Documentation Project Overview, the necessary tools may be installed.

1. Once installed, get a clean copy of the documentation source using git:

git clone https://git.FreeBSD.org/doc.git /usr/doc

The first download of the documentation sources might be time-consuming. Let it run till it completes.

2. Future updates to the documentation sources may be obtained by using the following command:

git pull

Once an up-to-date snapshot of the documentation sources has been retrieved to /usr/doc, the installed documentation may be updated.

3. A complete update may be executed by typing:

cd /usr/doc
make

How to Track a Development Branch?

Two development branches exist for FreeBSD:

• FreeBSD-CURRENT

• FreeBSD-STABLE

This section describes each branch and its target audience, as well as how to maintain a system's conformance with each branch.

How to Use FreeBSD-CURRENT?

FreeBSD-CURRENT represents the "bleeding edge" of FreeBSD development, and users are required to have a high level of technical expertise. Less technical users who desire to follow a development branch should instead follow FreeBSD-STABLE.

FreeBSD-CURRENT contains works in progress, experimental modifications, and transitional mechanisms that may or may not be included in the subsequent official version. Despite the fact that many FreeBSD engineers compile the FreeBSD-CURRENT source code on a regular basis, there are brief instances when the source code is not buildable. These issues are handled as rapidly as feasible, however, whether FreeBSD-CURRENT delivers catastrophe or new features depends on when the source code was synchronized.

FreeBSD-CURRENT is provided for three main interest groups:

1. Members of the FreeBSD community actively contributing to the source tree.

2. Active testers who are FreeBSD community members. They are willing to spend time resolving issues, proposing patches, and making pertinent comments about FreeBSD's future.

3. Users who desire to keep an eye on things, use the current source as a reference, or make the odd code contribution may do so by using the current source for reference reasons or by making the occasional remark.

FreeBSD-CURRENT should not be seen as a shortcut to obtaining new features before the next release, since pre-release features are not fully tested and are likely to have errors. Any given commit is equally likely to introduce new defects as it is to repair existing ones, making it a slow method for obtaining bug fixes. FreeBSD-CURRENT is not "officially supported" in any form.

For tracking FreeBSD-CURRENT:

1. Subscribe to the FreeBSD-CURRENT and Commit messages for the main branch of the src repository email lists. This is required to see people's comments on the current status of the system and to get relevant alerts about the current condition of FreeBSD-CURRENT. The Commit messages for the main branch of the src repository list document the commit log entry for each change, as well as any significant information on potential side effects. To subscribe to these lists, visit the FreeBSD list server, click on the desired list, and follow the on-screen instructions. To follow changes to the whole source tree, not just FreeBSD-CURRENT-specific changes, subscribe to the Commit messages for all branches of the src repository.

2. Sync with the sources of FreeBSD-CURRENT. git is often used to get the -CURRENT code from the main branch of the FreeBSD Git repository.

3. Due to the vastness of the repository, some users opt to synchronize just the areas of the source code that interest them or to which they have contributed changes. However, users who want to create the operating system from the source must obtain the whole FreeBSD-CURRENT distribution, not simply a subset. Before constructing FreeBSD-CURRENT, carefully review /usr/src/Makefile and adhere to the steps in Updating FreeBSD from Source. Read the FreeBSD-CURRENT mailing list and /usr/src/UPDATING to remain abreast of further bootstrapping methods that may become required on the path to the next release.

4. Be active! Users of FreeBSD-CURRENT are invited to contribute improvement requests and problem fixes. Code-accompanied suggestions are always appreciated.

How to Use FreeBSD-STABLE?

From the FreeBSD-STABLE development branch, major releases are generated. This branch receives modifications at a slower rate and with the presumption that they have been thoroughly tested in FreeBSD-CURRENT. This is still a development branch, and the FreeBSD-STABLE sources may or may not be appropriate for widespread usage at any given moment. It is only an additional technical development path and not a resource for end-users. Users who lack the resources for testing should instead use the latest version of FreeBSD.

Follow FreeBSD-STABLE if you are interested in tracking or contributing to the FreeBSD development process, particularly as it pertains to the upcoming FreeBSD release.

Even though the FreeBSD-STABLE branch should always build and execute, this cannot be guaranteed. Since more people use FreeBSD-STABLE than FreeBSD-CURRENT, it is inevitable that FreeBSD-STABLE would have problems and edge situations that were not visible in FreeBSD-CURRENT. Because of this, one should not blindly follow FreeBSD-STABLE. It is crucial that no production servers be updated to FreeBSD-STABLE until the code has been properly tested in a development or testing environment.

For tracking FreeBSD-STABLE:

1. Join the FreeBSD-STABLE mailing list to remain abreast of any build requirements that may arise in FreeBSD-STABLE, as well as any other problems needing particular attention. When developers are considering a contentious correction or update, they will post a notice to this mailing list, allowing users to reply if they have concerns about the planned change. Join the appropriate git list for the tracked branch. For instance, users following the 12-STABLE branch of the src repository should subscribe to the Commit notifications for the stable branches. This list documents the commit log entry and any applicable information on potential side effects for each change when it is made. To subscribe to these lists, visit the FreeBSD list server, click on the desired list, and follow the on-screen instructions. To follow changes to the whole source tree, subscribe to Commit notifications for all src repository branches.

2. Install the most current FreeBSD-STABLE version from the FreeBSD mirror sites or a monthly snapshot created from FreeBSD-STABLE to install a fresh FreeBSD-STABLE system. To build or update an existing FreeBSD system to FreeBSD-STABLE, check out the branch's source code using git. www.freebsd.org/releng lists branch names, such as stable/9.

3. Before building or upgrading to FreeBSD-STABLE, carefully review /usr/src/Makefile and adhere to the recommendations in Updating FreeBSD from Source. Read the FreeBSD-STABLE mailing list and /usr/src/UPDATING to stay abreast of additional bootstrapping processes that may become required on the path to the next release.

What is Release Number (N-number)?

When locating defects, it is essential to know which versions of the source code were used to build the system showing the issue. FreeBSD offers kernel-compiled version information. You may learn FreeBSD version by running the next command:

uname

You should see the output similar to the below:

FreeBSD 14.0-CURRENT #112 main-n148514-021250d67c18: Tue Jun 22 10:32:19 MDT 2021 alex@machine:/usr/home/alex/obj/usr/home/alex/git/head/amd64.amd64/sys/FRED

The final field contains information on the kernel's name, its creator, and the place where it was created. Regarding the fourth field, it consists of the following components:

1. main: Branch name in Git. n-number comparisons are only valid on project-published branches (main, stable/XX, and releng/XX). Local branches will have n-number`s that overlap with parent branch commits.

2. n247514:The n-number is a linear count of commits dating back to the beginning of the Git repository, beginning with the Git hash on the line.

3. 021250d67c18:Hash of the checked-out tree in Git.

4. When the kernel was compiled in a tree containing uncommitted modifications, a -dirty suffix may be present. This sample lacks it since the FRED kernel was compiled from a clean checkout.

To find the n-number corresponding to a Git hash, the git rev-list command is used.

git rev-list --first-parent  --count 021250d67c18
n148514

1. 021250d67c18:git hash to translate (the hash from the above example is reused)

2. n148514:The n-number

Typically, this number is of little significance. However, when bug fixes are committed, this number makes it simple to detect whether the patch is available in the system that is now active. Since the hash is the immediately discernible identifier for a change and the n-number is not, developers often refer to the hash of the commit (or offer a URL containing the hash) but not the n-number. Additionally, security advisories and errata announcements will provide an n-number, which may be compared directly with your system. You cannot compare n-numbers accurately when using shallow Git clones since the git rev-list tool counts all repository revisions, which a shallow clone omits.

How to Update FreeBSD From Source Code?

Compiling source code to update FreeBSD has various benefits over binary updates. Code may be constructed using choices that allow it to make use of certain hardware. Elements of the basic system may be constructed with non-default settings or omitted if they are not required or preferred. The build process takes longer than installing binary updates to update a system, but allows for extensive customization to generate a customized version of FreeBSD.

What are Quick Steps for FreeBSD Update From Source Code?

This is a brief reference for the common processes required to upgrade FreeBSD through source code compilation. In later parts, the method is described in more depth.

When switching from mergemaster to etcupdate, the initial run may improperly merge changes, resulting in bogus conflicts. To avoid this, before updating sources and constructing the new world, execute the following steps:

etcupdate extract
etcupdate diff

The first command will rebuild the database of stock /etc files.

The second command will examine the difference after bootstrapping. Eliminate local modifications that are no longer required to lessen the likelihood of future conflicts caused by upgrades.

1. To get the latest version of the source run the next command:

git pull /usr/src

2. Check /usr/src/UPDATING by running the following command:

check /usr/src/UPDATING

3. Go to the source directory.

cd /usr/src

4. Compile the everything except the kernel by running the next command:

make -j4 buildworld

5. To compile and install the kernel run the next command. This is equivalent to make buildkernel installkernel.

make -j4 kernel

6. Reboot the system to the new kernel by running the next command:

shutdown -r now

7. Update and merge configuration files in /etc/ required before installworld by running the following command:

etcupdate -p

8. Go to the source directory.

cd /usr/src

9. To install the world run the next command:

make installworld

10. Update and merge configuration files in /etc/by running the next command:

etcupdate -B

11. Restart the system to use the newly-built world and kernel.

shutdown -r now

How to Update From Source?

Firstly you should read /usr/src/UPDATING file. It describes any manual actions that must be completed before or after an update.

The location of the FreeBSD source code is /usr/src/. Git, a version control system, is the recommended technique for updating this content. Verify that the source code is under version control by running the next command:

cd /usr/src
git remote --v

You should see the output similar to the given below:

origin https://git.freebsd.org/src.git (fetch)
origin https://git.freebsd.org/src.git (push)

This indicates that /usr/src/ is under version control. You can update the source by using the following command:

git pull /usr/src

If the directory has not been updated lately, the process of updating might be time-consuming. After it completes, the source code is current and the build procedure outlined in the next section may begin.

How to Obtain the Source?

If the output of the git remote --v command is fatal: not a git repository, then it means that the source files are missing or they were installed with a different method and a fresh checkout of the source is necessary. You may follow the steps explained below to obtain the source:

1. Determine the version of FreeBSD that is in use by running the next command:

uname -r

You should see an output similar to the below:

13.1-RELEASE

uname -r Output	Repository Path	Description
X.Y-RELEASE	releng/X.Y	The Release version plus only essential security and bug fixes. This branch is suggested for the majority of users.
X.Y-STABLE	stable/X	The Release version together with all further work on that branch. STABLE indicates that the Applications Binary Interface (ABI) will not change, therefore software developed for previous versions will continue to function. For instance, software written to operate on FreeBSD 12.1 will continue to run on later-compiled FreeBSD 12-STABLE. Occasionally, STABLE branches have problems or incompatibilities that may harm users, although these are normally resolved rapidly.
X-CURRENT	main	The most recent unreleased version of FreeBSD. The CURRENT branch may include significant flaws or incompatibilities and is only advised for expert users.

Table 3. FreeBSD Versions and Repository Branches

Based on FreeBSD Versions and Repository Branches, the repository path for the source given in the above table is used. For example, To update 13.1-RELEASE releng/13.1 path is used during source checkout.

2. Remove the obsolete directory from use by running next command. If this directory has no local changes, it may be erased.

mv /usr/src /usr/src.bak

3. You may run the next common to checkout the source code. The repository URL is augmented with the path from FreeBSD Versions and Repository Branches. The third option specifies the local system target directory for the source code.

git clone --branch releng/13.1 https://git.FreeBSD.org/src.git /usr/src

You may see the output similar to the given below:

Cloning into '/usr/src'...
remote: Enumerating objects: 4204849, done.
remote: Counting objects: 100% (381096/381096), done.
remote: Compressing objects: 100% (28269/28269), done.
remote: Total 4204849 (delta 375313), reused 352827 (delta 352827), pack-reused 3823753
Receiving objects: 100% (4204849/4204849), 1.45 GiB | 2.90 MiB/s, done.
Resolving deltas: 100% (3335633/3335633), done.
Updating files: 100% (87481/87481), done.

How to Build from Source?

Except for the kernel, world, the whole operating system is compiled. This is performed initially to give up-to-date tools for kernel construction. The kernel is then constructed:

cd /usr/src
make buildworld
make buildkernel

The code is written to the /usr/obj directory.

These are the fundamental stages. Additional configuration choices are detailed below.

1. How to Implement Clean Build?

Some variants of the FreeBSD build system save previously built code in the /usr/obj temporary object directory. This may speed up subsequent builds by preventing the recompilation of unchanged code. Before beginning a build, use cleanworld to force a complete rebuild by running the next command:

make cleanworld

2. How to Set the Number of Jobs?

Increasing the number of build tasks on multicore processors helps accelerate the construction process. Determine the number of CPU cores with the sysctl hw.ncpu command. Processors vary, as do the build systems used with various versions of FreeBSD, therefore testing is the only reliable way to determine how the number of tasks impacts the build performance. Consider values between half and twice the number of cores as a starting point. -j specifies the number of jobs to be executed. For example, you may build the world and kernel with four jobs by running the next command:

make -j4 buildworld buildkernel

3. How to Build Only Kernel?

If the source code has been modified, a buildworld must be run. After that, buildkernel may be executed at any time to create a kernel. To build just the kernel you may run the next commands:

cd /usr/src
make buildkernel

4. How to Build Custom Kernel?

The basic FreeBSD kernel is based on the GENERIC kernel configuration file. The GENERIC kernel contains the most frequently used device drivers and configuration settings. Occasionally it is beneficial or required to develop a custom kernel by adding or deleting device drivers and settings to meet a particular purpose.

For instance, a developer of a tiny embedded computer with highly constrained RAM may eliminate unnecessary device drivers or choices to make the kernel significantly smaller.

The location of the kernel configuration files is /usr/src/sys/arch/conf, where arch is the result of uname -m. On the majority of machines, the configuration file directory is /usr/src/sys/amd64/conf/.

tip

Custom kernel configuration files should be kept in a different directory, such as /root, since /usr/src may be erased or regenerated. Connect the kernel configuration file to the conf folder. If this directory is destroyed or replaced, the kernel configuration may be relinked to the new location.

You may copy the GENERIC config file to produce a custom config file by running the next commands. The new custom kernel for a storage server is called STORAGESERVER in this example.

cp /usr/src/sys/amd64/conf/GENERIC /root/STORAGESERVER
cd /usr/src/sys/amd64/conf
ln -s /root/STORAGESERVER

/root/STORAGESERVER is modified, adding or deleting devices or parameters as specified in config documentation.

The custom kernel is created by specifying the kernel configuration file (KERNCONF) on the command line:

make buildkernel KERNCONF=STORAGESERVER

How to Install Compiled Code?

After you complete the buildworld and buildkernel explained above, the new kernel and world are installed by following steps given below.

1. To install the kernel run the next commands and reboot your system.

cd /usr/src
make installkernel
shutdown -r now

If you have built a custom kernel, KERNCONF must also be set to use the new custom kernel by running next commands:

cd /usr/src
make installkernel KERNCONF=STORAGESERVER
shutdown -r now

2. After the system gets up and running, To install the world run the next commands and reboot your system.

cd /usr/src
make installworld
shutdown -r now

How to Complete Update?

Several remaining tasks conclude the upgrade. The system is restarted after any updated configuration files are combined with the new versions, obsolete libraries are discovered and deleted, and then any modified configuration files are merged with the new versions.

1. How to Combine Configuration Files Using etcupdate?

etcupdate is a utility for handling updates to files that are not updated by an installworld, such as /etc/ files. It maintains updates by merging changes made to these files with the local copies. It is likewise meant to need little user interaction, unlike mergemaster that has interactive prompts.

etcupdate does not need any explicit parameters to perform its function. There is, however, you can verify the correctness of the first etcupdate operation by running the next command:

etcupdate diff

This command enables auditing of configuration modifications.

If etcupdate is unable to automatically merge a file, the merge conflicts may be handled manually by running the next command:

etcupdate resolve

warning

When moving from mergemaster(8) to etcupdate(8), the initial run may improperly merge changes, resulting in bogus conflicts. To avoid this, before updating sources and constructing the new world, execute the following steps:

1. Rebuild the database of stock /etc files by running the following command:

etcupdate extract

2. To examine the difference after bootstrapping run the next command. Eliminate local modifications that are no longer required to lessen the likelihood of future conflicts caused by upgrades.

etcupdate diff

2. How to Merge Configuration Files with mergemaster?

mergemaster enables the merging of modified system configuration files with updated versions of those files. mergemaster is a substitute for the recommended etcupdate. To automatically update unmodified files and installs new files that are not already present run the next command:

mergemaster -Ui

If a file must be manually merged, an interactive interface enables the user to choose which elements of the files are to be retained.

3. How to Verify Expired Files and Libraries?

After an upgrade, certain outdated files or folders may persist. To find these files run the next command:

make check-old

To remove expired files, run the next command:

make delete-old

Some outdated libraries may continue to exist. These may be identified by running the next command::

make check-old-libs

To remove the old libraries run the following command:

make delete-old-libs

Programs that were still using these obsolete libraries will cease to function after the library has been removed. After removing the old libraries, these programs must be rebuilt or replaced.

tip

By specifying BATCH_DELETE_OLD_FILES in the command, typing y and Enter to delete each file may be avoided when it is known that all old files and folders are safe to remove.

make BATCH_DELETE_OLD_FILES=yes delete-old-libs

4. Restarting Following the Update

Rebooting the FreeBSD system is the last step after an update to ensure that all changes take effect.

shutdown -r now

How to Track for Several Systems?

When several FreeBSD systems need to track the same source tree, it is a waste of disk space, network traffic, and CPU cycles for each system to download the sources and rebuild the whole system. The answer is for one system to do the majority of the work, while the other machines mount it over NFS. This section describes how to do this.

Initially, designate a group of computers that will execute the same set of binaries, often known as a build set. Each computer may have its own kernel, but they will all use the same userland binaries.

1. Choose a computer from that collection to serve as the build machine for the world and kernel. This is ideally a fast system with enough free CPU to execute make buildworld and make buildkernel.

2. Choose a computer to serve as the test machine, which will test software upgrades prior to their implementation in production. This machine must be able to withstand a lengthy period of downtime. It need not be the construction machine, but it might be.

3. Each computer inside this build set must mount /usr/obj and /usr/src over NFS from the build machine. For multiple build sets, /usr/src should be located on one system and NFS should be mounted on the others.

4. Ensure that /etc/make.conf and /etc/src.conf are identical on each computer in the build set and the build machine. This implies that the build machine must construct all components of the base system that will be installed by any machine in the build set. In addition, each build machine's kernel name should be specified using KERNCONF in /etc/make.conf, and the build machine should list them all in its KERNCONF, starting with its own kernel. /usr/src/sys/arch/conf must include the kernel configuration files for each computer on the build machine.

5. On the build computer, build the kernel and world according to the instructions in How to Update FreeBSD from Source, but do not install anything. Install the produced kernel on the test computer instead. Using NFS, mount /usr/src and /usr/obj on the test system. Then, execute shutdown now to enter single-user mode so that the new kernel and world can be installed, then run mergemaster as normal. Reboot to revert to regular multi-user operations once completion.

6. After checking that everything is functioning successfully on the test computer, install the updated software on the other machines in the build set using the same approach.

The similar concept is applicable to the ports tree. The first step is to share /usr/ports through NFS with all build set computers. To configure /etc/make.conf to share distfiles, specify DISTDIR to a shared directory that is readable by whichever user root the NFS mount is assigned to. WRKDIRPREFIX must be set to a local build directory on each system if ports are to be created locally. Set PACKAGES on the build system to a directory similar to DISTDIR if the build system is to create and distribute packages to the computers in the build set.