1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
# 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=<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](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
|
