ZFS combines the roles of volume manager and independent file system into one, giving multiple advantages over a stand-alone file system. It is renowned for speed, flexibility, and, most importantly, taking great care to prevent data loss. While many traditional file systems had to exist on a single disk at a time, ZFS is aware of the underlying structure of the disks and creates a pool of available storage, even on multiple disks. The existing file system will grow automatically when extra disks are added to the pool, immediately becoming available to the file system.

FreeBSD can mount ZFS pools and datasets during system initialization. To enable it, add this line to /etc/rc.conf:

Then start the service:

Before setting up ZFS, identify the device names of the disk associated with the system. A quick way of doing this is with:

The output should identify the device names, examples throughout the rest of this guide will use the default SCSI names: da0, da1, and da2. If the hardware differs, make sure to use the correct device names instead.

To create a simple, non-redundant pool using a single disk device:

To create files for users to browse within the pool:

The new file can be viewed using ls:

We can already start using more advanced ZFS features and properties. To create a dataset within the pool with compression enabled:

The example/compressed dataset is now a ZFS compressed file system.

Disable compression with:

To unmount a file system, use zfs umount and then verify with df:

Verify that example/compressed is not included as a mounted file under the output.

The file system can be re-mounted with zfs:

With the file system mounted, the output should include a line similar to the one below:

ZFS datasets are created just like any other file system, the following example creates a new file system called data:

Use df to see the data and space usage (some of the output has been removed for clarity)

Because these file systems are built on ZFS, they draw from the same pool for storage. This eliminates the need for volumes and partitions that other file systems rely on.

To destroy the file systems and then the pool that is no longer needed:

RAID-Z pools require three or more disks but offer protection from data loss if a disk were to fail. Because the ZFS pools can use multiple disks, support for RAID is inherent in the design of the file system

To create a RAID-Z pool, specifying the disks to add to the pool:

With the zpool created, a new file system can be made in that pool:

Enable compression and store an extra copy of directories and files:

A RAID-Z pool is a great place to store crucial system files, such as the home directory for users. To make the file system the home new home directory :

File system snapshots can be created to roll back to later, the snapshot name is marked in red and can be whatever you want:

ZFS creates snapshots of a dataset, allowing users to back up a file system for roll backs or data recovery in the future.

To list all available snapshots, zfs list can be used:

Every software RAID has a method of monitoring its state. View the status of RAID-Z devices using:

If all pools are Online and everything is normal, the message shows:

If there is a problem, perhaps a disk being in the Offline state, the pool state will look like this:

“OFFLINE” shows the administrator took da1 offline using:

Power down the computer now and replace da1. Power up the computer and return da1 to the pool:

Next, check the status again, this time without -x to display all pools:

ZFS uses checksums to verify the integrity of stored data, these data checksums can be verified (which is called scrubbing) to ensure integrity of the storage pool:

Only one scrub can be run at a time due to the heavy input/output requirements. The length of the scrub depends on how much data is store in the pool.After scrubbing completes, view the status with zpool status:

Displaying the completion date of the last scrubbing helps decide when to start another. Routine scrubs help protect data from silent corruption and ensure the integrity of the pool.

ZFS has two main utilities for administration: The zpool utility controls the operation of the pool and allows adding, removing, replacing, and managing disks. The zfs utility allows creating, destroying, and managing datasets, both file systems and volumes.

While this introductory guide won’t cover ZFS administration, you can refer to zfs(8) and zpool(8) for other ZFS options.

A wireless networking card is required to use a wireless network, FreeBSD will also need to be configured to the correct wireless network support. The correct module will need to be modified, depending on the type of networking card. The most commonly used wireless devices are those that use parts made by Atheros. These devices are supported by ath(4) and require the following line to be added to /boot/loader.conf:

If unsure about the device, you can identify many common wireless adaptors through the use of the  sysctl(8) net.wlan.devices variable:

To load support for a different type of wireless device, specify the module for that device. This example is for devices based on the Intersil Prism parts (wi(4)) driver:

Note: A list of available wireless drivers and supported adapters can be found in the FreeBSD Hardware Notes, available on the Release Information page of the FreeBSD website.

In addition, the modules that implement cryptographic support for the security protocols to use must be loaded. These are intended to be dynamically loaded on demand by the wlan(4) module. To load these modules at boot time, add the following lines to /boot/loader.conf:

Information about the wireless device should appear in the boot messages, like this:

Directly connecting to an unsecure network, while not recommended, is extremely common. It’s also a very simple process on FreeBSD. In this example I’ll beconnecting to the John F Kennedy International Airport’s free WiFi.

Start by finding the name of the network:

This will look for available networks and return a list, In this case, we want to connect to the JFK free wifi so we’ll use:

Hopefully you will see that it’s joined, and running ifconfig ath0 will show that it’s associated. You can then get an address with:

Most home/private networks will rely on these security protocols. Connecting a computer to an existing WPA/WPA2/Personal wireless network is a very common situation.

FreeBSD can act as an Access Point (AP) in order to act as a gateway or to eliminate the need to purchase AP hardware. Before an Access Point can be set up, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. This mode is only supported by native FreeBSD wireless drivers.

After setting up wireless networking, you can check if the device supports host-based access point mode:

This output displays the card’s capabilities. The HOSTAP word confirms that this wireless card can act as an AP.

The wireless device can only be put into hostap mode during the creation of the network pseudo-device, so a previously created device must be destroyed first:

then regenerated with the correct option before setting the other parameters:

Use ifconfig(8) again to see the status of the wlan0 interface:

The hostap parameter indicates the interface is running in the host-based access point mode.

The interface configuration can be done automatically at boot time by adding the following lines to /etc/rc.conf:

Once the AP is configured, initiate a scan from another wireless machine to find the AP.

Many cellphones can share data connection over USB, FreeBSD provides support through a variety of protocols:

Before attaching a device, load the appropriate driver into the kernel:

Once the device is attached ue0 will be available for use like a normal network device. Be sure that the “USB tethering” option is enabled on the mobile device.

To make this change permanent and load the driver as a module at boot time, place the appropriate line of the following in /boot/loader.conf:

Before attaching a Bluetooth device, determine which Bluetooth driver it uses. A broad variety of Bluetooth USB dongles are supported by ng_ubt(4). Broadcom BCM2033 based Bluetooth devices are supported by the ubtbcmfw(4) and ng_ubt(4) drivers. The 3Com Bluetooth PC Card 3CRWB60-A is supported by the ng_bt3c(4) driver. Serial and UART based Bluetooth devices are supported by sio(4), ng_h4(4), and hcseriald(8). For example, if the device uses the ng_ubt(4) driver:

If the Bluetooth device will be attached to the system during system startup, the system can be configured to load the module at boot time by adding the driver to /boot/loader.conf:

Once the driver is loaded, plug in the USB dongle. If the driver load was successful, output similar to the following should appear on the console and in /var/log/messages:

To start and stop Bluetooth, use the driver’s startup script.

FreeBSD uses hccontrol(8) to find and identify Bluetooth devices within RF proximity.

One of the most common tasks is discovery of Bluetooth devices within RF proximity. This operation is called inquiry. Inquiry and other HCI related operations are done using hccontrol(8). To display a list of devices that are in range use:

Note: only devices that are set to discoverable mode will be listed.

The BD_ADDR is the unique address of a Bluetooth device, similar to the MAC address of a network card. This address is needed for further communication with a device. To to obtain the human readable name that was assigned to the remote device:

The Bluetooth system provides a point-to-point connection between two Bluetooth units, or a point-to-multipoint connection which is shared among several Bluetooth devices. The following example shows how to create a connection to a remote device:

create_connection accepts BT_ADDR as well as host aliases in /etc/bluetooth/hosts.

The following example shows how to obtain the list of active baseband connections for the local device:

While a Bluetooth device can choose to require authentication, communication is normally not authenticated, so any Bluetooth device can talk to any other device. If the device requires authentication, the PIN code must be entered on both devices, the devices will then generate a link key. After that, the link key can be stored either in the devices or in a persistent storage. This procedure is called pairing.

The hcsecd(8) daemon is responsible for handling Bluetooth authentication requests. The default configuration file is /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with the PIN code set to 1234 is shown below:

The only limitation on PIN codes is length. Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. The -d switch forces hcsecd(8) to stay in the foreground, so it is easy to see what is happening. Set the remote device to receive pairing and initiate the Bluetooth connection to the remote device. The remote device should indicate that pairing was accepted and request the PIN code. Enter the same PIN code listed in hcsecd.conf. Now the computer and the remote device are paired.

The following line can be added to /etc/rc.conf to configure hcsecd(8) to start automatically on system start:

Updated: June 15, 2022

With FreeBSD’s ongoing migration to git from subversion, the system for updating FreeBSD from source has adapted. This guide will cover getting sources from git, updating them, and how to bisect those sources. It is meant as an introduction to the new mechanics for general users.

To begin, the source tree must be downloaded. This can be done quite simply. First step: cloning a tree. This downloads the entire tree. There are two ways to download. By default, git will do a deep clone, which matches what most people want. However, there are times that you may wish to do a shallow clone.

The branch names in the new git repository are similar to the subversion names. For the stable branches, they are stable/X where X is the major release number (like 12 or 13). The development branch for -CURRENT in the new repository is main.

Note: The main branch is the default branch if you omit the -b branch options below.

The hashes are different between them. For migrating from the old repository to the new one, please refer to https://github.com/freebsd/freebsd-legacy/commit/de1aa3dab23c06fec962a14da3e7b4755c5880cf

Use the repository of choice in place of $URL in the following commands.

Before cloning the tree, git will need to be installed. The simplest way of doing so is through packages.

# pkg install git

There are also git-lite and git-tiny, two packages with only essential dependencies available. They are sufficient for the commands in this article.

A deep clone pulls in the entire tree, as well as all the history and branches. It’s the easiest to do. It also allows you to use git’s worktree feature to have all your active branches checked out into separate directories but with only one copy of the repository.

% git clone $URL -b branch [dir]

is how you make a deep clone. branch should be one of the branches listed in the section 1.1, if omitted, it will be the depository’s default: main. Dir is an optional directory to place it in (the default will be the name of the repository you are clone (src). For example:

% git clone https://git.freebsd.org/src.git

You’ll want a deep clone if you are interested in the history, plan on making local changes, or plan on working on more than one branch. It’s the easiest to keep up to date as well. If you are interested in the history, but are working with only one branch and are short on space, you can also use
--single-branch to only download the one branch (though some merge commits will not reference the merged-from branch which may be important for some users who are interested in detailed versions of history).

A shallow clone copies just the most current code, but none or little of the history. This can be useful when you need to build a specific revision of FreeBSD, or when you are just starting out and plan to track the tree more fully. You can also use it to limit history to only so many revisions.

% git clone -b branch --depth 1 $URL [dir]

An example using the default branch:

% git clone --depth 1 https://git.freebsd.org/src.git

This clones the repository, but only has the most recent revision in the repository. The rest of the history is not downloaded. Should you change your mind later, you can do git fetch --unshallow to get the complete history.

After cloning the FreeBSD repository, the next step is to build from source. The process of building remains relatively unchanged, using make and install. Git and offer git pull and git checkout for updating and selecting specific branches or revisions.

Building can be done as described in the handbook [3], eg:

% cd src
% make buildworld
% make buildkernel
% make installkernel
% make installworld

Note that you can specify -j to make to speed up with parallelism.

The following command will update both types of trees. This will pull all revisions since the last update.

% git pull --ff-only

This will update the tree. In git, a fast forward merge is one that only needs to set a new branch pointer and doesn’t need to re-create the commits. By always doing a fast forward merge/pull, you’ll ensure that you have an identical copy of the FreeBSD tree. This will be important if you want to maintain local patches.

See below for how to manage local changes. The simplest is to use:

% git pull --autostash

but more sophisticated options are available.

In git, the git checkout command can be used to checkout a specific revision as well as branches. Git’s revisions are the long hashes rather than a sequential number.

When you checkout a specific revision, just specify the hash you want on the command line (the git log command can help you decide which hash you might want):

% git checkout 08b8197a74

However, as with many things git, it’s not so simple. You’ll be greeted with a message similar to the following:

where the last line is generated from the hash you are checking out and the first line of the commit message from that revision. Hashes can also be abbreviated. That’s why you’ll see them have different lengths in different commands or their outputs. These super long hashes are often unique after some characters, depends on the size of the repository so git lets you abbreviate and is somewhat inconsistent about how it presents them to users. git rev-parse --short <full-hash> will show the short hash which has the enough length to distinguish in the repository. The current length of FreeBSD src repository is 12.

Sometimes, things go wrong. The last revision worked, but the one you just updated to does not. A developer may ask to bisect the problem to track down which commit caused the regression.

If you’ve read the last section, you may be thinking to yourself “How the heck do I bisect with crazy revision numbers like that?” then this section is for you. It’s also for you if you didn’t think that, but also want to bisect.

Fortunately, git offers the git bisect command. Here’s a brief outline in how to use it. For more information, I’d suggest https://git-scm.com/docs/git-bisect for more details. The man page is good at describing what can go wrong, what to do when revisions won’t build, when you want to use terms other than good and bad, etc, none of which will be covered here.

git bisect start will start the bisection process. Next, you need to tell a range to go through. git bisect good XXXXXX will tell it the working revision and git bisect bad XXXXX will tell it the bad revision. The bad revision will almost always be HEAD (a special tag for what you have checked out). The good revision will be the last one you checked out.

A quick aside: if you want to know the last revision you checked out, you should use git reflog:

shows me moving the working tree to the master branch (a816…) and then updating from upstream (to 5ef0…). In this case, bad would be HEAD (or 5rf0bd68) and good would be a8163e165. As you can see from the output, HEAD@{1} also often works, but isn’t foolproof if you’ve done other things to your git tree after updating, but before you discover the need to bisect.

Back to git bisect. Set the good revision first, then set the bad (though the order doesn’t matter). When you set the bad revision, it will give you some statistics on the process:

% git bisect start
% git bisect good a8163e165c5b
% git bisect bad HEAD

You’d then build/install that revision. If it’s good you’d type git bisect good otherwise git bisect bad. You’ll get a similar message to the above each step. When you are done, report the bad revision to the developer (or fix the bug yourself and send a patch). git bisect reset will end the process and return you back to where you started (usually tip of main). Again, the git-bisect manual (linked above) is a good resource for when things go wrong or for unusual cases.

The doc tree is the first repository converted to git. There is only one development branch in the repository, main, which contains the source of https://www.freebsd.org and https://docs.freebsd.org.

The ports tree operates a similar way. The branch names are different and the repos are in different locations.

As with ports, the latest development branch is main. The quarterly branches are named the same as in FreeBSD’s svn repo. They are used by the latest and quarterly branches of the pkg.

Here’s a small collection of topics that are more advanced for the user tracking FreeBSD. If you have no local changes, you can stop reading now (it’s the last section and OK to skip).

One item that’s important for all of them: all changes are local until pushed. Unlike svn, git uses a distributed model. For users, for most things, there’s very little difference. However, if you have local changes, you can use the same tool to manage them as you use to pull in changes from FreeBSD. All changes that you’ve not pushed are local and can easily be modified (git rebase, discussed below does this).

The simplest way to keep local changes (especially trivial ones) is to use git stash. In its simplest form, you use git stash to record the changes (which pushes them onto the stash stack). Most people use this to save changes before updating the tree as described above. They then use git stash apply to re-apply them to the tree. The stash is a stack of changes that can be examined with git stash list. The git-stash man page (https://git-scm.com/docs/git-stash) has all the details.

This method is suitable when you have tiny tweaks to the tree. When you have anything non trivial, you’ll likely be better off keeping a local branch and rebasing. It is also integrated with the git pull command: just add
––autostash to the command line.

It’s much easier to keep a local branch with git than subversion. In subversion you need to merge the commit, and resolve the conflicts. This is manageable, but can lead to a convoluted history that’s hard to upstream should that ever be necessary, or hard to replicate if you need to do so. Git also allows one to merge, along with the same problems. That’s one way to manage the branch, but it’s the least flexible.

Git has a concept of ‘rebasing’ which you can use to avoid these issues. The git rebase command will basically replay all the commits relative to the parent branch at a newer location on that parent branch. This section will briefly cover how to do this, but will not cover all scenarios.

Let’s say you want to make a hack to FreeBSD’s ls(1) command to never, ever do color. There’s many reasons to do this, but this example will use that as a baseline. The FreeBSD ls(1) command changes from time to time, and you’ll need to cope with those changes. Fortunately, with git rebase it usually is automatic.

% cd src
% git checkout main
% git checkout -b no-color-ls
% cd bin/ls
% vi ls.c # hack the changes in
% git diff # check the changes

% # these look good, make the commit...
% git commit ls.c

The commit will pop you into an editor to describe what you’ve done. Once you enter that, you have your own local branch in the git repo. Build and install it like you normally would, following the directions in the handbook. git differs from other revision control systems in that you have to tell it explicitly which files to use. Here it’s done on the commit command line, but you can also do it with git add which many of the more in depth tutorials cover.

When it’s time to bring in a new revision, it’s almost the same as w/o the branches. You would update like you would above, but there’s one extra command before you update, and one after. The following assumes you are starting with an unmodified tree. It’s important to start rebasing operations with a clean tree (git usually requires this).

% git checkout main
% git pull
% git rebase -i main no-color-ls

This will bring up an editor that lists all the commits in it. For this example, don’t change it at all. This is typically what you are doing while updating the baseline (though you also use the git rebase command to curate the commits you have in the branch).

Once you’re done with the above, you’ve moved the commits to ls.c forward from the old revision of FreeBSD to the newer one.

Sometimes there’s merge conflicts. That’s OK. Don’t panic. You’d handle them the same as you would any other merge conflicts. To keep it simple, I’ll just describe a common issue you might see. A pointer to a more complete treatment can be found at the end of this section.

Let’s say this includes changes upstream in a radical shift to terminfo as well as a name change for the option. When you updated, you might see something like this:

which looks scary. If you bring up an editor, you’ll see it’s a typical 3-way merge conflict resolution that you may be familiar with from other source code systems (the rest of ls.c has been omitted):

The new code is first, and your code is second. The right fix here is to just add a #undef COLORLS_NEW before #ifdef and then delete the old changes:

save the file. The rebase was interrupted, so you have to complete it:

% git add ls.c
% git rebase --cont

which tells git that ls.c has changed and to continue the rebase operation. Since there was a conflict, you’ll get kicked into the editor to maybe update the commit message.

If you get stuck during the rebase, don’t panic. git rebase –abort will take you back to a clean slate. It’s important, though, to start with an unmodified tree.

For more on this topic, https://www.freecodecamp.org/news/the-ultimate-guide-to-git-merge-and-git-rebase/ provides a rather extensive treatment. It goes into a lot of cases I didn’t cover here for simplicity that are useful to know since they come up from time to time.

Let’s say you want to main the jump from FreeBSD stable/12 to FreeBSD current. That’s easy to do as well, if you have a deep clone.

% git checkout main
% # build and install here...

and you are done. If you have a local branch, though, there’s one or two caveats. First, rebase will rewrite history, so you’ll likely want to do something to save it. Second, jumping branches tends to encounter more conflicts. If we pretend the example above was relative to stable/12, then to move to main, I’d suggest the following:

% git checkout no-color-ls
% git checkout -b no-color-ls-stable-12 # create another name for this branch
% git rebase -i stable/12 no-color-ls --onto main

What the above does is checkout no-color-ls. Then create a new name for it (no-color-ls-stable-12) in case you need to get back to it. Then you rebase onto the main branch. This will find all the commits to the current no-color-ls branch (back to where it meets up with the stable/12 branch) and then it will replay them onto the main branch creating a new no-color-ls branch there (which is why I had you create a placeholder name).

[1] Using Git, FreeBSD Handbook, https://docs.freebsd.org/en/books/handbook/mirrors/#git

[2] Git, FreeBSD wiki, https://wiki.freebsd.org/Git

[3] Updating FreeBSD from Source, FreeBSD Handbook, https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld