FreeBSD Wifibox/Alpine

The purpose of this repository is to maintain all the configuration files and scripts that are used for rolling out a FreeBSD Wifibox guest based on Alpine Linux.

Warning

This is a work-in-progress experimental software project without any guarantees or warranties. It is shared in the hope that is going to be useful and inspiring for others. Please report issues at the FreeBSD Wifibox repository directly.

Prerequisites

For building the virtual disk image, the following third-party software is employed, which must be installed beforehand.

• SquashFS Tools NG or the sysutils/squashfs-tools-ng FreeBSD package.
• GNU Tar or the archivers/gtar FreeBSD package.
• PatchELF or the sysutils/patchelf FreeBSD package.

Note that the build process also uses native 64-bit Linux binaries, that is why the Linuxulator must be activated by loading the linux64 kernel module.

# kldload linux64

Installation

Whenever possible, use the net/wifibox-alpine FreeBSD port from the freebsd-wifibox-port repository, which aims to automate the tasks described below and offers proper removal of the install files.

Manual Installation

There is a Makefile present in the root of the repository that could be used to drive the installation process. It is mostly recommended for development and testing.

# make install \
	PREFIX=<prefix> \
	LOCALBASE=<prefix of third-party software> \
	MINIROOTFS=<Alpine minimal root file system tarball> \
	PACKAGES=<Alpine package set> \
	BOOT_SERVICES=<services to launch on boot> \
	DEFAULT_SERVICES=<default services> \
	SYSINIT_SERVICES=<system initialization services> \
	ETC_SRCS=<location of application-specific configuration files> \
	EXTRA_VIRTFS_MOUNTS=<fstab entries for shared file systems> \
	FIRMWARE_FILES=<List of firmware files to keep> \
	SQUASHFS_COMP=<Squashfs compression type>

The following make(1) variables are available to control the build process:

• PREFIX is optional, it is set to /usr/local by default. This is the prefix under which the guest's file system will be constructed, in the share/wifibox/guest sub-directory. It is possible to set the LOCALBASE variable as well to tell if the prefix under which various third-party utilities, such as git and mksquashfs were installed is different.

• MINIROOTFS should point to the Alpine minimal root file system tarball for the x86_64 architecture, which is going to be used in the bootstrapping phase. Such tarballs can be retrieved from the Alpine Linux web site. By default, that is set to alpine-minirootfs.tar.gz.

• PACKAGES should tell which Alpine Linux packages to install for the guest. Those are all must be local files with the .apk extension. By default, that is *.apk, which means that all available packages are looked up in the current directory and utilized during the installation process.

• BOOT_SERVICES should specify which OpenRC services have to be launched on booting the guest. They greatly depend on what the installed packages provide.

• DEFAULT_SERVICES should set which services are launched by default. Their actual set depends on the contents of the installed packages.

• SYSINIT_SERVICES should tell which services are launched as part of the guest system initialization phase, along with the kernel. They have to be sync with the installed packages.

• ETC_SRCS should point to a location where the guest's generic configuration files could be found. This helps to choose between application-specific configuration defaults. Currently, such files are offered for wpa_supplicant and hostapd, see the etc directory in the repository.

• EXTRA_VIRTFS_MOUNTS can optionally contain information about further 9P/VirtFS entries for the guest's /etc/fstab file. First, the VirtFS share has to be named, which is then followed by the location where it should be mounted in the guest. These are separated by a :, visually:

  share:/target/directory
  

• FIRMWARE_FILES is to tell which exact firmware files to keep to reduce further the size of the disk image. It is optional, mostly recommended in case of iwlwifi.

• SQUASHFS_COMP configures the compression method used for building the Squashfs file system. By default, that is the rather conservative lzo setting, but lz4, gzip, xz, and zstd are also available.

Besides these, it is considered that a directory named guest might be present for holding further files and directories that shall be added to the virtual disk image, under its root.

Documentation

There is a manual page available that describes how the guest can be used once installed.

# man wifibox-alpine