13.2 Updating FreeBSD from Source

Building FreeBSD from source allows customization of kernel options and compilation parameters, suitable for architectures not supported by freebsd-update or scenarios requiring a trimmed system.

The basic approach is to obtain the FreeBSD source code, then compile and install it. You can use Git to pull the code directly, download txz compressed files from the FreeBSD download site, or download the zip archive of the current FreeBSD project from GitHub.

For the compilation process, refer to other chapters in this book.

Obtaining Source Code from Git

Installing Git

Install Git using pkg:

# pkg install git

Or install Git using Ports:

# cd /usr/ports/devel/git/
# make install clean

Git Proxy Configuration

In restricted network environments, you may need to configure a proxy for Git to pull source code properly. Below are methods for setting and removing Git proxies.

• Set Git global proxy:

# git config --global http.proxy http://192.168.X.X:7890  # Set Git global HTTP proxy
# git config --global https.proxy http://192.168.X.X:7890  # Set Git global HTTPS proxy

• Remove Git global proxy:

# git config --global --unset http.proxy  # Remove Git global HTTP proxy setting
# git config --global --unset https.proxy  # Remove Git global HTTPS proxy setting

Pulling Source Code with Git

Pulling CURRENT

Pull the source code from the official FreeBSD repository. Clone the FreeBSD source repository to /usr/src using a shallow clone to reduce download size:

$ git clone --depth 1 https://git.FreeBSD.org/src.git /usr/src

Explanation of the --depth 1 parameter: Uses shallow clone mode, fetching only the latest commit without the complete commit history.

Pull the source code from GitHub (GitHub is a mirror of the src repository on FreeBSD.org, synchronized every 10 minutes).

$ git clone --depth 1 https://github.com/freebsd/freebsd-src /usr/src

Pulling a Specific RELEASE

Pull from the official FreeBSD repository. Clone the FreeBSD 15.0 release branch source code to /usr/src, using a shallow clone with only that branch:

$ git clone --branch releng/15.0 --single-branch --depth 1 https://git.freebsd.org/src.git /usr/src

Option explanation:

• --branch releng/15.0: Specifies the branch to pull (the version of the FreeBSD RELEASE)
• --single-branch: Clones only one branch, containing no other refs besides the single cloned branch.

Or pull from GitHub. Clone the FreeBSD 15.0 release branch source code to /usr/src from GitHub, using a shallow clone with only that branch:

$ git clone --branch releng/15.0 --single-branch --depth 1 https://github.com/freebsd/freebsd-src /usr/src

References

• Warner Losh. Submitting GitHub Pull Requests to FreeBSD[EB/OL]. [2026-03-25]. https://freebsdfoundation.org/our-work/journal/browser-based-edition/configuration-management-2/submitting-github-pull-requests-to-freebsd/. Detailed explanation of the workflow and considerations for submitting pull requests to FreeBSD via GitHub.

Obtaining Source Code from Compressed Archives (Convenient but Not Latest)

This method is simple to operate.

Taking FreeBSD 15.0-RELEASE as an example:

# fetch https://download.freebsd.org/releases/amd64/amd64/15.0-RELEASE/src.txz  # Download the FreeBSD 15.0-RELEASE source code archive
# tar xvf src.txz -C /                                                    # Extract the source code to the root directory

Why extract to /?

Because the archive contains paths, extracting to / will place the source code in /usr/src. If you change the path above to /usr/src, the source code will be extracted to /usr/src/usr/src.

Tip

If the download is slow, you can switch to https://mirrors.ustc.edu.cn/freebsd/releases/amd64/amd64/15.0-RELEASE/src.txz

Starting the Build

# cd /usr/src          # Switch to the working directory
# make -j4 buildworld  # Build world
# make -j4 kernel      # Build and install the kernel (equivalent to buildkernel followed by installkernel)
# reboot               # Reboot to use the new kernel
# cd /usr/src          # Switch back to the working directory
# etcupdate -p         # Merge configuration files that must be updated before installworld
# make installworld    # Install world
# etcupdate -B         # Reuse the previously built object tree to merge updates
# reboot               # Reboot to complete the update process

Appendix: Resolving Conflicts

• Conflicts remain from previous update, aborting.

Conflicts need to be resolved.

Tip

Unlike most modern Linux distributions, vi on FreeBSD (and OpenBSD) is nvi (a reimplementation of the original ex/vi), not a symbolic link to vim. This editor is used infrequently, so it is recommended to switch to another text editor.

export EDITOR=/usr/bin/ee # Switch the default editor to ee. If using csh/tcsh, use setenv EDITOR /usr/bin/ee instead
export VISUAL=/usr/bin/ee # Switch the visual editor to ee. If using csh/tcsh, use setenv VISUAL /usr/bin/ee instead

Merge conflicts. Use etcupdate to merge configuration file updates:

# etcupdate -B
Conflicts remain from previous update, aborting.

etcupdate automatically triggers post-processing for several system files after merging:

Changed File	Triggered Command
/etc/master.passwd	pwd_mkdb
/etc/login.conf	cap_mkdb
/etc/mail/aliases	newaliases
/etc/services	services_mkdb
/etc/localtime (when /var/db/zoneinfo exists)	tzsetup
/etc/motd	/etc/rc.d/motd

Resolve conflicts:

# etcupdate resolve          # Resolve conflicts
Resolving conflict in '/etc/group':
Select: (p) postpone, (df) diff-full, (e) edit,
        (h) help for more options: e # Enter e to resolve the conflict
# etcupdate -B

Troubleshooting and Outstanding Issues

Git: fatal: unable to update url base from redirection

The FreeBSD source repository address was used without the .git suffix.

Git: fatal: unable to access 'https://git.FreeBSD.org/src.git/': SSL certificate problem: certificate is not yet valid

This is caused by incorrect system time. Use ntpd -q -g pool.ntp.org to synchronize the system time. For detailed instructions, refer to other relevant chapters in this book.

References

• FreeBSD Foundation. 2021 in Review: Software Development[EB/OL]. [2026-04-16]. https://freebsdfoundation.org/blog/2021-in-review-software-development/
• FreeBSD Project. etcupdate -- manage updates to system files not updated by installworld[EB/OL]. [2026-03-25]. https://man.freebsd.org/cgi/man.cgi?query=etcupdate&sektion=8. Official technical documentation for the system configuration file update tool.

Exercises

1. Summarize the complete process of obtaining source code from the FreeBSD Git repository, listing the required commands and their parameter meanings.
2. Use etcupdate to manage configuration file updates in the /etc directory, and document a complete conflict resolution process.
3. Modify /etc/src.conf to exclude unnecessary components (such as certain debugging tools), and measure the change in make buildworld compilation time.