path: root/man/wifibox-alpine.5

.Dd April 30, 2022
.Dt WIFIBOX-ALPINE 5
.Os
.Sh NAME
.Nm wifibox-alpine
.Nd wifibox based on Alpine Linux
.Sh INTRODUCTION
The implementation of the
.Xr wifibox 8
embedded wireless router is based on the use of a Linux-based guest
operating system which can communicate with the host's wireless
network card on behalf of the host.  In order to meet the requirements
of this setup, this has to be a system with a low resource footprint
and easy to manage.
.Pp
This solution is derived from Alpine Linux, which is an actively
maintained, security-oriented, lightweight distribution, based on musl
libc and busybox.  For more information and introduction to the tools
that are going to be used in the sections below, please visit the
following sites:
.Pp
.Bl -bullet -compact
.It
Alpine Linux:
.ft B
https://alpinelinux.org/
.ft R
.It
BusyBox:
.ft B
https://busybox.net/
.ft R
.It
OpenRC:
.ft B
http://www.gentoo.org/proj/en/base/openrc/
.ft R
.It
iw:
.ft B
https://wireless.wiki.kernel.org/en/users/documentation/iw
.ft R
.El
.Sh IMPLEMENTATION
The guest is created with a
.Sy root
user, which is associated with a blank password.  This can only be
used to login to the guest via the
.Cm console
command of
.Xr wifibox 8 ,
no other services are configured for remote access.
.Pp
Although the
.Sy root
user possesses unlimited access to every resource inside the guest,
files cannot be changed.  That is because the operating system is
built in a way that it does not require any write access to the
contents of the root file system.  In addition to that, all the
contents of the disk image is stored in a compressed format via
SquashFS and uncompressed to memory only on demand.  Everything that
needs to be modified during the guest's run time is stored on
dedicated file systems that are either memory-backed or shared with
the host.
.Pp
For the ease of management, the host shares configuration files with
the services that are responsible for implementing the domain logic.
.Bl -bullet
.It
.Sy wpa_supplicant
works with the
.Pa wpa_supplicant.conf
file and handles the configuration of the wireless networks.  This is
the same tool that is used in the FreeBSD base system for the same
purpose, and it is utilized here to make it possible to reuse the
configuration files of the same format.
.It
.Sy ifup
and
.Sy ifdown
work with the
.Pa interfaces.conf
file to associate the internal network interfaces with IP addresses:
.Sy wlan0
is the wireless device which is automatically configured through DHCP,
.Sy eth0
is the virtual Ethernet device which is configured according to the
contents of the configuration file.
.It
.Sy udhcpd
works with the
.Pa udhcpd.conf
file and implements a DHCP server for
.Sy eth0
so that it can hand out IP addresses in a given range for the host and
set itself the default gateway for forwarding the network traffic.  It
also manages the distribution of information about the name servers.
This is utilized only when the host is configured to do so.
.It
.Sy wpa_passthru
works with the
.Pa wpa_ctrl.conf
file that is shared with the host and manages the forwarding of
control sockets created for
.Sy wpa_supplicant .
When enabled, it attemps to parse the contents of
.Pa wpa_supplicant.conf
to learn if there are sockets available and exposes them over the
configured TCP ports with the help of
.Sy socat .
Note that a heavily stripped-down version of
.Sy socat
is installed to minimize the related security risks.
.El
.Pp
The generic configuration files are read from the
.Pa /media/etc
directory where the
.Sy config
9P (VirtFS) share is mounted in read-only mode.  From there, the files
are hooked up in the system in the following ways.
.Bl -bullet
.It
.Pa /media/etc/interfaces.conf
is mapped to
.Pa /etc/network/interfaces.conf
which is included as part of
.Pa /etc/network/interfaces
when managed by
.Sy ifup
and
.Sy ifdown .
.It
.Pa /media/etc/udhcpd.conf
is mapped to
.Pa /etc/udhcpd.conf
where
.Sy udhcpd
will read its contents.
.It
.Pa /media/etc/wpa_ctrl.conf
is not mapped to anywhere under
.Pa /etc ,
it is used directly from there by
.Sy wpa_passthru .
.El
.Pp
The
.Pa wpa_supplicant.conf
configuration file is shared with the host through the
.Pa /media/wpa
directory where the
.Sy wpa_config
9P (VirtFS) share is mounted.  This will let
.Sy wpa_supplicant
change the contents when instructed to do so from the host through the
forwarded control sockets and permitted by the configuration.
.Pp
The variable data files under the guest's
.Pa /var
directory are shared with the host by mounting the
.Sy var
9P (VirtFS) share there.  This includes streaming out all the logs
under the
.Pa /var/log
directory, such as
.Pa /var/log/dmesg
or
.Pa /var/log/messages
so that the internal state of the guest can be tracked by accessing
these files on the host.  The contents of the
.Pa /var/run
directory will not be visible on the host, as it is stored only in the
memory.
.Pp
Further components of the guest that are not directly configurable or
visible to the outside:
.Bl -bullet
.It
.Sy busybox
is a combination of tiny versions of the common UNIX utilities,
including the
.Sy ash
shell itself, shipped in a single small executable.  It provides the
execution environment for all the scripts and services.  All the
irrelevant modules were removed for security hardening.
.It
.Sy iptables
implements the forwarding (Network Address Translation, NAT) between
the
.Sy eth0
and
.Sy wlan0
interfaces.  The respective rules are static and they are stored in
the
.Pa /etc/iptables/rules-save
configuration file.
.It
The base layout of the Alpine sytem is stripped down to the bare
minimum, and for example, the guest does not have the
.Sy apk
package manager installed since it would be able to work.  Instead,
the disk image itself should be constructed in a way that it includes
all the needed applications.
.El
.Sh STARTING, STOPPING, AND RESTARTING SERVICES
Every service running on the guest can be managed by the
.Sy rc-service
(locate and run OpenRC service) command, which is going to be used in
this section.  The list of actively managed services can be learned as
follows.
.Bd -literal -offset indent
# rc-service --list
.Ed
.Pp
The status of a specific service can be queried by the
.Cm status
command.  For example, the
.Sy wpa_supplicant
tool has its own associated service and it can be checked by the following
command.
.Bd -literal -offset indent
# rc-service wpa_supplicant status
.Ed
.Pp
Similary to this, the
.Cm start ,
.Cm stop ,
and
.Cm restart
commands are available as well to start, stop, or restart the given
service, respectively.  In the example below, consider re-initializing
all the network interfaces by restarting the
.Sy networking
service.
.Bd -literal -offset indent
# rc-service networking restart
.Ed
.Pp
These commands can help with troubleshooting and restoring the
respective services in case of failures.
.Sh WIRELESS DIAGNOSTICS
Details of wireless configuration can be learned through the use of
the
.Sy iw
tool, which is suitable for showing and manipulating wireless devices
and their configuration.  For example, it can list the device
capabilities, such as band information (2.4 GHz and 5 GHz), and
802.11n information.
.Bd -literal -offset indent
# iw list
.Ed
.Pp
Scanning can be initiated as follows.  There,
.Sy wlan0
is the name of the wireless networking device, which can be considered
constant.
.Bd -literal -offset indent
# iw dev wlan0 scan
.Ed
.Pp
Wireless events can be traced with the
.Cm event
command.  In the related example below, the
.Fl f
and
.Fl t
flags are added to show full frames for auth/assoc/deauth/disassoc as
well as the timestamps for each event.
.Bd -literal -offset indent
# iw event -t -f
.Ed
.Pp
To determine if there is an active connection to an Access Point and
further related information can be displayed by the
.Cm link
command.
.Bd -literal -offset indent
# iw dev wlan0 link
.Ed
.Pp
More details can be collected by the
.Cm station dump
command.
.Bd -literal -offset indent
# iw dev wlan0 station dump
.Ed
.Sh SUPPORTED HARDWARE
There are a number of Linux drivers available as kernel modules.  Note
that not all of them could be used immediately because there might be
additional, often proprietary firmware files have to be placed under
.Pa /lib/firmware
for activation.
.Pp
.Bl -tag -width Ds -offset indent -compact
.It ADMTek/Infineon AMD8211A
.It ADMTek/Infineon AMD8211B
.It ADMTek/Infineon AMD8211C
.It Atmel at76c506
.It Broadcom BCM4301
.It Broadcom BCM4306/2
.It Broadcom BCM4306/3
.It Broadcom BCM4311
.It Broadcom BCM4312
.It Broadcom BCM4313
.It Broadcom BCM43131
.It Broadcom BCM43142
.It Broadcom BCM4318
.It Broadcom BCM4321
.It Broadcom BCM43217
.It Broadcom BCM4322
.It Broadcom BCM43222
.It Broadcom BCM43224
.It Broadcom BCM43225
.It Broadcom BCM43227
.It Broadcom BCM43228
.It Broadcom BCM4331
.It Broadcom BCM4352
.It Broadcom BCM4360
.It Cisco Aironet 350 Series PCI-351
.It Cisco Aironet 350 Series PCI-352
.It Intel(R) PRO/Wireless 2100
.It Intel(R) PRO/Wireless 2200/2915
.It Intel(R) PRO/Wireless 3945ABG/BG
.It Intel(R) Wireless WiFi 4965
.It Intel(R) Centrino(R) Wireless-N 1000
.It Intel(R) Centrino(R) Wireless-N 1030
.It Intel(R) Centrino(R) Wireless-N 100
.It Intel(R) Centrino(R) Wireless-N 105
.It Intel(R) Centrino(R) Wireless-N 130
.It Intel(R) Centrino(R) Wireless-N 135
.It Intel(R) Centrino(R) Wireless-N 2200
.It Intel(R) Centrino(R) Wireless-N 2230
.It Intel(R) Centrino(R) Ultimate-N 5100
.It Intel(R) Centrino(R) Ultimate-N Wi-Fi Link 5300
.It Intel(R) Centrino(R) WiMAX/Wi-Fi Link 5350
.It Intel(R) Centrino(R) Advanced-N + WiMAX 6150
.It Intel(R) Centrino(R) Advanced-N 6200
.It Intel(R) Centrino(R) Advanced-N 6205
.It Intel(R) Centrino(R) Advanced-N 6230
.It Intel(R) Centrino(R) Advanced-N 6235
.It Intel(R) Centrino(R) Advanced-N + WiMAX 6250
.It Intel(R) Centrino(R) Ultimate-N 6300
.It Intel(R) Wireless 3160
.It Intel(R) Wireless 7260
.It Intel(R) Wireless 7265
.It Intel(R) Wireless-AC 3165
.It Intel(R) Wireless-AC 3168
.It Intel(R) Wireless-AC 8260
.It Intel(R) Wireless-AC 8265
.It Intel(R) Wireless-AC 9260
.It Intel(R) Wireless-AC 9461
.It Intel(R) Wireless-AC 9462
.It Intel(R) Wireless-AC 9560
.It Intel(R) Wi-Fi 6 AX200
.It Intel(R) Wi-Fi 6 AX201
.It Intel(R) Wi-Fi 6 AX210
.It Intel(R) Wi-Fi 6 AX211
.It Marvell 88W8363
.It Marvell 88W8366
.It Marvell 88W8387
.It Marvell 88W8764
.It Marvell 88W8766
.It Marvell 88W8897
.It MediaTek MT7603E
.It MediaTek MT7610E
.It MediaTek MT7612/MT7602/MT7662
.It MediaTek MT7615
.It MediaTek MT7622
.It MediaTek MT7628
.It MediaTek MT7630E
.It MediaTek MT7663
.It MediaTek MT7915
.It MediaTek MT7921
.It Qualcomm Atheros AR2413
.It Qualcomm Atheros AR2414
.It Qualcomm Atheros AR2415
.It Qualcomm Atheros AR2417
.It Qualcomm Atheros AR2423/4
.It Qualcomm Atheros AR2425
.It Qualcomm Atheros AR2427
.It Qualcomm Atheros AR5210
.It Qualcomm Atheros AR5211
.It Qualcomm Atheros AR5212
.It Qualcomm Atheros AR5213
.It Qualcomm Atheros AR5214
.It Qualcomm Atheros AR5416
.It Qualcomm Atheros AR5418
.It Qualcomm Atheros AR9102
.It Qualcomm Atheros AR9103
.It Qualcomm Atheros AR9160
.It Qualcomm Atheros AR9220
.It Qualcomm Atheros AR9223
.It Qualcomm Atheros AR9227
.It Qualcomm Atheros AR9280
.It Qualcomm Atheros AR9281
.It Qualcomm Atheros AR9285
.It Qualcomm Atheros AR9287
.It Qualcomm Atheros AR9331
.It Qualcomm Atheros AR9340
.It Qualcomm Atheros AR9380
.It Qualcomm Atheros AR9382
.It Qualcomm Atheros AR9462
.It Qualcomm Atheros AR9485
.It Qualcomm Atheros AR9550
.It Qualcomm Atheros AR9565
.It Qualcomm Atheros AR9580
.It Qualcomm Atheros IPQ4018
.It Qualcomm Atheros IPQ8074
.It Qualcomm Atheros IPQ6018
.It Qualcomm Atheros QCA6174 / QCA6174A
.It Qualcomm Atheros QCA6390
.It Qualcomm Atheros QCA9337
.It Qualcomm Atheros QCA9880
.It Qualcomm Atheros QCA9882
.It Qualcomm Atheros QCA9886
.It Qualcomm Atheros QCA9888
.It Qualcomm Atheros QCA9890
.It Qualcomm Atheros QCA9892
.It Qualcomm Atheros QCA9984
.It Qualcomm Atheros QCN9074
.It Qualcomm Atheros WCN6855
.It Quantenna QSR10G
.It Ralink RT2460
.It Ralink RT2560
.It Ralink RT2501/RT2561/RT2561S (RT61)
.It Ralink RT2600/RT2661 (RT61)
.It Ralink RT2760
.It Ralink RT2790
.It Ralink RT2800
.It Ralink RT2860
.It Ralink RT2890
.It Ralink RT3052
.It Realtek 8180
.It Realtek 8185
.It Realtek 8187SE
.It Realtek 8188E
.It Realtek 8192EE
.It Realtek 8192C/8188C
.It Realtek 8192S/8191S
.It Realtek 8192DE
.It Realtek 8723BE
.It Realtek 8723D
.It Realtek 8723DE
.It Realtek 8723E
.It Realtek 8821AE
.It Realtek 8822B
.It Realtek 8822BE
.It Realtek 8822C
.It Realtek 8822CE
.It Realtek 8821C
.It Realtek 8821CE
.It Realtek 8852AE
.It Texas Instruments WL1271/3
.It Texas Instruments WL1281/3
.El
.Sh SEE ALSO
.Xr wifibox 8
.Sh AUTHORS
.An Gábor Páli Aq Mt pali.gabor@gmail.com