FreeBSD Installation and Configuration

This page contains the steps to download, install, configure, and update the FreeBSD operating system. This guide was done with a clean installation in mind, i.e., it doesn't take into account any possiblity of doing an upgrade from an older FreeBSD version to the new one.

Created: 1/4/2022
Updated: 1/7/2022

Official Documentation

This guide contains my notes, which may be inaccurate or outdated. The official website of FreeBSD is www.freebsd.org. The official documentation is in the FreeBSD Handbook and FreeBSD FAQ.

FreeBSD Branches

There are three branches of FreeBSD:

-RELEASE
-STABLE
-CURRENT

The -RELEASE branch (e.g., 13.0-RELEASE, 13.1-RELEASE, etc.) contains the tested and released build of FreeBSD, and can be used in production.

The -STABLE branch is a development branch for the next point-release of the -RELEASE branch (e.g., bug fixes and improvements to the 13.0-RELEASE are done in 13.0-STABLE, from which a 13.1-RELEASE is then created and released. The -STABLE branch is less tested, and may be less stable, than a -RELEASE branch, but it may contain important improvements and bug fixes that haven't made it to a -RELEASE yet.

The -CURRENT branch contains the latest FreeBSD development code. The code from -CURRENT will eventually become the next -RELEASE version (e.g., 14.0-CURRENT will become a 14.0-RELEASE).

Alternatives to FreeBSD on Desktop Computers

FreeBSD doesn't come with any graphical user interface (although a graphical user interface can be installed manually). There are some user-friendly derivatives of FreeBSD that come with a graphical user interface and additional software configured. Some of them are:

GhostBSD
MidnightBSD
helloSystem

GhostBSD is based on the -STABLE branch of FreeBSD, so it contains fixes that haven't made it to a -RELEASE branch yet. Overall, it seems like the most solid option of the three. The installer doesn't offer an option to encrypt data on the hard drive, though.

MidnightBSD uses the -RELEASE branch of FreeBSD, so it currently (January 2022) doesn't boot on my laptop that needs UEFI and ACPI fixes from the -STABLE branch.

helloSystem tries to implement a desktop environment that follows old Macintosh graphical design. The downloadable image successfully booted in UEFI mode, but did not contain ACPI fixes for my laptop (as of January 2022).

Download the FreeBSD Installation Image

The installation image can be downloaded from the FreeBSD website. Note that the .iso images don't work when written to a USB flash drive. For USB drives, use a -memstick.img image instead.

Before Installation

Boot from the FreeBSD installation media, select the "Live CD" option, and login as the root user with no password.

Remove Old EFI Boot Entries

If there are any boot entries defined in UEFI for any operating system that isn't installed anymore or which will be replaced by this FreeBSD installation, the boot entries can be easily removed.

List EFI boot entries:

# efibootmgr

Delete any old entries:

# efibootmgr -B -b NUM

(Optional) Erase Hard Drive

When performing a clean installation, I prefer TRIMming the whole capacity of an SSD to achieve the best SSD performance for new operating system installations. On HDDs, I prefer at least erasing the partition table and the MBR record so that the installer of the new operating system sees an empty hard drive and doesn't try to keep any existing partitions.

Get a list of connected hard drives:

# geom disk list

Option 1: Only remove the partition table from the target drive:

# gpart destroy -F DRIVE

Option 2: TRIM the whole drive (if the drive supports it):

# trim -f /dev/DRIVE

Option 3: Overwrite the drive with zeros (not recommended on SSDs):

# dd if=/dev/zero of=/dev/DRIVE bs=4m status=progress

If the drive contained any partitions before, I recommend doing a reboot. The installer will then see an empty drive and will not attempt to open encrypted partitions, for example.

Installation

Boot from the FreeBSD installation media and proceed with the installation.

Use a fully-qualified hostname (e.g., david-pc.davidgroup instead of only david-pc) to avoid issues with some system components like sendmail.
During user creation, when an Invite USER into other groups? []: message is displayed, type wheel and operator (separated by a space) to make the user an administrator who has privileges to perform operations with hardware, like powering off the computer.
The choice of a shell (sh, tcsh, …) doesn't really matter since I prefer to replace it with bash or zsh anyway.

After Installation

When the installation is complete, reboot to the newly installed FreeBSD operating system. Login as a regular user. I prefer logging in as a regular user and switching to the root user later if needed as opposed to logging in as the root user directly.

Setup sudo

Instead of having to switch to a superuser's account for each privileged command, I recommend setting up sudo.

$ su -
# pkg update
# pkg install sudo
# visudo # Uncomment one of the %wheel lines at the end of the configuration file
# exit

Install ZSH

ZSH is a shell similar to Bash. Because of its license, it is used in macOS by default.

$ sudo pkg install zsh
$ chsh -s /usr/local/bin/zsh
$ # OR:
$ pw usermod USERNAME -s /usr/local/bin/zsh

Logout, log back in. An initial ZSH configuration will run. Then, add the following lines to the ~/.zshrc file:

autoload -Uz compinit
compinit
PROMPT="%n@%m %1~ %# "

Enable SSD TRIM

Enable automatic TRIM:

$ sudo zpool set autotrim=on zroot

Run a manual TRIM:

$ sudo zpool trim zroot

Install Microcode Updates

Install the sysutils/devcpu-data port or package. Then, add the following line to the /boot/loader.conf configuration file:

cpu_microcode_load="YES"
cpu_microcode_name="/boot/firmware/intel-ucode.bin"

Alternatively (or concurrently), activate a microcode update service. Add to /etc/rc.conf:

microcode_update_enable="YES"

Modify FreeBSD Configuration

Some FreeBSD configuration can be changed post-install via a simple text user interface.

$ sudo bsdconfig

How to Install Software

There are two ways of installing additional software: ports and packages. Ports contain source code that needs to be compiled. Packages are already compiled.

Binary Packages

To install packages, use the pkg tool. Note that updates in the -STABLE and -CURRENT branches of FreeBSD may break ABI compatibility. In that case, building a package from ports may be a better idea than installing binary packages to avoid incompatibilities, especially when installing drivers.

The FreeBSD package repository offers two package sets — latest and quarterly. Refer to the FreeBSD handbook for more information.

To update the package database, run:

$ sudo pkg update

To search for packages and install packages, run:

$ sudo pkg search
$ sudo pkg install PACKAGE

To list installed packages:

$ sudo pkg prime-list
$ sudo pkg leaf

Ports (Build From Source)

To compile and install ports, you can use the portsnap tool (if using the -RELEASE branch of FreeBSD), or build the code manually. There are also tools like Synth or Poudriere that create an isolated environment, build the port in it, create a package, and provide the package in a local repository for installation by pkg.

Option 1: Using portsnap (when using -RELEASE):

$ sudo portsnap fetch
$ sudo portsnap extract
$ sudo portsnap fetch
$ sudo portsnap update

Option 2: Using git:

$ sudo pkg install git
$ sudo git clone --depth 1 https://git.freebsd.org/ports.git /usr/ports

And then build and install ports by:

$ cd /usr/ports/ORIGIN/PORT
$ sudo make install clean

How to Install Updates

There are two ways of installing updates. Supported FreeBSD releases offer binary updates. The alternative option is building a FreeBSD source code.

Binary Updates

Binary updates are available only for supported -RELEASE branches of FreeBSD. To install updates, run:

$ sudo freebsd-update fetch
$ sudo freebsd-update install

Refer to the FreeBSD documentation for more information regarding system updates and upgrades between major FreeBSD releases.

Build From Source

First, download the FreeBSD source code. Depending on the installed FreeBSD branch, checkout the correct git branch. For example, checkout the

main git branch if using the -CURRENT FreeBSD branch,
stable/X branch if using -STABLE,
releng/X.Y branch if using -RELEASE.

$ sudo pkg install git
$ sudo git clone --branch BRANCH --depth 100 https://git.freebsd.org/src.git /usr/src
$ sudo git -C /usr/src pull

An alternative option is downloading a tar archive with the source code for released versions of FreeBSD.

$ fetch ftp://ftp.freebsd.org/pub/FreeBSD/releases/amd64/RELEASE/src.txz
$ sudo tar -C / -xvf src.txz

Then, build the source and install the compiled files. Note that the build process may take a considerable amount of time to finish.

$ cd /usr/src
$ sudo make cleanworld # optional
$ sudo ee /etc/src.conf # set WITH_MALLOC_PRODUCTION=yes
$ sudo make -j8 buildworld
$ sudo make -j8 kernel KERNCONF="GENERIC-NODEBUG"
$ shutdown -r now
$ sudo etcupdate -p
$ cd /usr/src
$ sudo make installworld
$ sudo etcupdate -B
$ shutdown -r now

Note that the line

$ sudo make kernel KERNCONF=...

is equivalent to:

$ sudo make buildkernel KERNCONF=...
$ sudo make installkernel KERNCONF=...

Make sure the EFI bootloader is also updated:

$ sudo cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi
$ sudo cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi

Install Graphical User Interface

By default, FreeBSD operates in text mode. This section describes the steps to install a graphical desktop environment.

Install Graphics Drivers

First, install GPU drivers. I am using the integrated Intel HD graphics.

Option 1: A binary package with the driver can be used if using FreeBSD-RELEASE.

$ sudo pkg install drm-kmod

Option 2: The binary driver from the package may not work if using FreeBSD-CURRENT or -STABLE. In that case, build the driver manually from ports.

$ cd /usr/ports/graphics/drm-current-kmod
$ sudo make install clean

Enable the driver by adding the following line to /etc/rc.conf and rebooting.

kld_list="i915kms"

Add the user to the video group.

$ sudo pw groupmod video -m USER

Install X11 Server

Next, install an X11 server. FreeBSD doesn't support Wayland reliably yet.

$ sudo pkg install xorg

Install Desktop Environment

This section describes the steps to install the Xfce desktop environment. Installing other environments like KDE, Mate or GNOME would be similar.

Install the desktop environment.

$ sudo pkg install xfce

Enable and start the Xfce desktop environment.

$ echo ". /usr/local/etc/xdg/xfce4/xinitrc" > ~/.xinitrc
$ startx

Machine-Specific Settings

These settings are specific to my Sandy-Bridge laptop.

Persist UEFI Console Resolution

The boot loader allows the specification of different GOP resolutions. To persist the setting, add the following line to /boot/loader.conf:

exec="gop set NUM"

Configure LCD Backlight

On a laptop with an Intel integrated GPU, use the intel_backlight command to configure the display backlight. This example sets the backlight to 30% of its maximum brightness.

$ sudo pkg install intel-backlight
$ intel_backlight 30

Disable Nvidia GPU (Optimus)

I never made the secondary Nvidia graphics card work under FreeBSD on my laptop. To disable the graphics card so that it doesn't draw power, use the script mentioned in the FreeBSD wiki.

$ sudo pkg install acpi_call
$ sudo kldload acpi_call
$ fetch https://people.freebsd.org/~xmj/turn_off_gpu.sh
$ ee turn_off_gpu.sh # Replace ` with ' in the echo line
$ sudo sh ./turn_off_gpu.sh