vlc-record-2025-07-09-04h24m00s-tarbsd.mp4-.mp4

tarBSD is a minimal (well, depends on chosen features and packages) FreeBSD image that boots to memory. Most of it is stored in a tar archive mounted at /usr. tarBSD is not a distribution unto itself. Instead, this repository gives you a tool to build your own version of it.

Because most of tarBSD is in a tightly compressed (zstd-19) tar archive, which is mounted rather than extracted at boot, it doesn't need nearly as much ram as traditional mfs images. Depending on installed packages and chosen features, the image can be even smaller than 40 megabytes.

Possible use cases for tarBSD

• router
• NAS
• virtualization host
• all the above in a one box
• a remote FreeBSD installer with SSH

Design goals

• simple to use, yet configurable to suit wide range of use cases
• just one configuration file + an overlay directory
• pkgbase
• tightly compressed

Installing the builder tool

pkg/ports

sysutils/tarbsd-builder is available in the ports tree. Compared to the GitHub version, it installs dependencies and manages any potential changes to them automatically.

GitHub release

Download it from the releases page. In order to run it, you'll need an existing FreeBSD system with PHP >= 8.2 along with some extensions. GitHub version can be updated with the self-update command. Compared to the port version, updates are available immidiatelly upon release.

# make tarbsd builder executable
# and move it to /usr/local/bin
chmod +x tarbsd
mv tarbsd /usr/local/bin/tarbsd

# dependencies
pkg install php85-phar php85-zlib php85-filter php85-pcntl php85-mbstring php85-intl

# (optional) pigz for better kernel compression
pkg install pigz

Usage

Start by creating a project directory and using tarbsd bootstrap command there.

mkdir myproject
cd myproject
tarbsd bootstrap

It'll ask few questions, create a configuration file as well as an overlay directory, which contents will be recursively copied to the image. You'll likely want to edit tarbsd.yml and tarbsd/etc/rc.conf at least.

Building the image

First build will take longer due to base packages download, but they're cached for future use.

# RELEASE version
tarbsd build --release 15.1

# LATEST here could mean STABLE or CURRENT depending on version
tarbsd build --release 15-LATEST

When in hurry, pass --quick option to the builder. You'll get the image quicker, but it will be bigger and require more memory to boot. For small images, size difference might not be huge, but it gets bigger as /usr gets bigger. Useful for builds that are intended to be just prototypes anyway.

tarbsd build --release 15.1 --quick

Raw .img (for bhyve, kvm and real computers) is always generated. If you have qemu installed, it can also be converted to all sorts of random formats.

tarbsd build --release 15.1 qcow qcow2 vdi vmdk vhdx vpc parallels

Verbose output doesn't quite show every single little detail yet, but if you like tar -v and pkg install being streamed to your console, you can have them.

tarbsd build --release 15.1 -v

Mounting ZFS datasets

tarBSD comes with an rc script, which imports zfs pools upon boot. Use in conjuction with zfs_enable in your rc.conf and remember to enable zfs in tarbsd.yml.

# import zpools tank_a and tank_b at boot
tarbsd_zpools="tank_a tank_b"

# mount zfs datasets at boot
zfs_enable="YES"

Once your image is ready

tarBSD image gets built in a in-memory file system. Once your image is ready, you might want to destroy the file system in order to free memory.

tarbsd wrk-destroy

tarbsd.yml options

root_pwhash

A hashed root password.

root_sshkey

SSH key (public version).

backup

Backup tarbsd.yml as well as the overlay directory inside the image. If you loose the computer, which created the image, you've got backup inside the image itself assuming it runs on another computer and you haven't lost that one too.

busybox

Replaces many applications with busybox. Might break some shell scripts and some commands might not behave exactly in a way you're used to.

ssh (dropbear|openssh|null)

Dropbear is slightly smaller. tarBSD does some tricks here to share the host keys between the two, so you can switch easily without re-keying clients. No OpenSSH also means no base kerberos.

platform

Amd64 (default) or aarch64.

features

Things such as ZFS, bhyve and wireguard etc that are only needed by some and thus, are opt-in. Depending on feature, it will include relevant kernel modules, userland tools and sometimes packages. Please, suggest new ones (or send pr) if you think something is missing.

modules

Two lists (early and late) of kernel modules to be included in the image. Early modules are loaded immediately upon boot, while the late ones will be available later.

packages

List of packages to be installed.

Other miscellaneous things

• tarBSD lives in memory. If you need non-volatile storage, you need to mount it. If you mount something in /usr (which is read-only), make a corressponding empty directory to tarbsd/usr, so it can be mounted.
• Because the image is built using in-memory file system, the system running the builder needs to have adequate amount of usable memory.
• Builder will automatically add fstab line for following pseudo filesystems if the kernel module is present either through a feature or manual include:
  • procfs
  • fdescfs
  • linprocfs (automatically included in busybox builds)
  • linsysfs
• SSH is on by default unless there's no SSH program. You can disable it by setting sshd_enabled="NO" or dropbear_enable="NO" in etc/rc.conf.
• Base packages and compressed kernels are cached at /var/cache/tarbsd and this cache is shared across all tarbsd projects you might have. Other things such as port packages are cached locally at the project up until next boot.
• Aarch64 images might not boot on every random development board due to their non-standard boot procedures. Raspberry pi for example, doesn't work yet, but support is planned.

Contributing

There's a compiler in the stubs directory. It spits out the executable, which is a phar archive. During development, you can just require vendor/autoload.php, create TarBSD\App and run that, but do at least occasional testing with a phar app too.

If you're not familiar with Symfony components, here's the docs. Relevant parts here are console, process, filesystem and finder.

Builder's predecessor was a shell script and there might be some random leftovers of it in the code. Going forward, file access happens in PHP and not PHP invoking /bin/cp, /bin/rm and /bin/ln. Obvious exceptions to this are cases where tar, makefs or something of that sort is needed.