https://github.com/pgj/freebsd-wifibox-alpine
FreeBSD wifibox guest based on Alpine Linux
https://github.com/pgj/freebsd-wifibox-alpine
Last synced: 4 months ago
JSON representation
FreeBSD wifibox guest based on Alpine Linux
- Host: GitHub
- URL: https://github.com/pgj/freebsd-wifibox-alpine
- Owner: pgj
- License: bsd-2-clause
- Created: 2022-02-17T01:40:14.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-09-20T14:35:26.000Z (9 months ago)
- Last Synced: 2025-09-20T14:50:42.237Z (9 months ago)
- Language: Shell
- Homepage:
- Size: 569 KB
- Stars: 10
- Watchers: 4
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
```console
# 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.
```console
# make install \
PREFIX= \
LOCALBASE= \
MINIROOTFS= \
PACKAGES= \
BOOT_SERVICES= \
DEFAULT_SERVICES= \
SYSINIT_SERVICES= \
ETC_SRCS= \
EXTRA_VIRTFS_MOUNTS= \
FIRMWARE_FILES= \
SQUASHFS_COMP=
```
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](https://alpinelinux.org/downloads/). 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.
```console
# man wifibox-alpine
```
[FreeBSD Wifibox]: https://github.com/pgj/freebsd-wifibox
[Alpine Linux]: https://alpinelinux.org/
[SquashFS Tools NG]: https://infraroot.at/projects/squashfs-tools-ng/
[GNU Tar]: https://www.gnu.org/software/tar/
[PatchELF]: https://github.com/NixOS/patchelf
[Linuxulator]: https://docs.freebsd.org/en/books/handbook/linuxemu/
[freebsd-wifibox-port]: https://github.com/pgj/freebsd-wifibox-port/
[OpenRC]: https://github.com/OpenRC/openrc