path: root/man/wifibox-alpine.5

.Dd June 16, 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
iptables:
.ft B
https://www.netfilter.org/projects/iptables/index.html
.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 might not be changed in every case.  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
The image can host either
.Sy wpa_supplicant
for connecting to wirelss networks, or
.Sy hostapd
for creating wireless access points, depending how it was built.  Each
application-specific detail is going to be included below.
.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/wpa_supplicant.conf
file, while
.Sy hostapd
works with the
.Pa hostapd/hostapd.conf
file.  These are the same tools that are used in the FreeBSD base
system for the same purpose, and their Linux version is utilized here
to make it possible to reuse the configuration files of the same
format from the host.
.It
.Sy ifup
and
.Sy ifdown
work with the
.Pa appliance/interfaces.conf
file to associate the internal network interfaces with IP addresses:
.Sy wlan0
is the wireless device and
.Sy eth0
is the virtual Ethernet device towards the host which are both
configured according to the contents of the configuration file.
.It
.Sy iptables
works with the
.Pa appliance/iptables
file and it is responsible for moving network packets (Network Address
Translation, NAT) between the
.Sy eth0
and
.Sy wlan0
interfaces.  The configuration file describes the flow of the network
packets through the interfaces.  It is loaded once at launching the
respective service, usually on boot, and cannot be modified from the
guest.
.It
.Sy udhcpd
works with the
.Pa appliance/udhcpd.conf
file and it can implements a DHCP server for either
.Sy eth0
or
.Sy wlan0
so that it can hand out IP addresses in a given range for the host
.Sy ( wpa_supplicant )
or the clients on the wireless network
.Sy ( hostapd ) ,
and can 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 dynamic IP addresses are in
use.
.It
.Sy uds_passthru
is an optional service for managing the forwarding of control sockets
created for either
.Sy wpa_supplicant
or
.Sy hostapd .
It works with the
.Pa appliance/uds_passthru.conf
file that is shared with the host.  This file is optional, and when it
is present, it automatically implies that service is enabled.  The
contents describe what sockets should be exposed over configured TCP
ports with the help of
.Sy socat ,
which a heavily stripped-down version of the original tool to minimize
the related security risks.
.El
.Pp
The
.Pa appliance
directory on the host holds the generic configuration files.  They 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 directly included as part of
.Pa /etc/network/interfaces
when managed by
.Sy ifup
and
.Sy ifdown .
.It
.Pa /media/etc/iptables
is used directly from this location by
.Sy iptables .
.It
.Pa /media/etc/udhcpd.conf
is mapped to
.Pa /etc/udhcpd.conf
where
.Sy udhcpd
will read its contents.
.It
.Pa /media/etc/uds_passthru.conf
is used directly from this location by
.Sy uds_passthru .
.El
.Pp
The
.Pa wpa_supplicant/wpa_supplicant.conf
or
.Pa hostapd/hostapd.conf
configuration file is shared with the host through the
.Pa /etc/wpa_supplicant
or the
.Pa /etc/hostapd
directory respectively, where the
.Sy app_config
9P (VirtFS) share is mounted.  This will let
.Sy wpa_supplicant
or
.Sy hostapd
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
Version 5.15 (LTS) of the Linux kernel and its wireless drivers are
used to communicate with exposed hardware.  It does not always work
with the latest ones, see the section on supported hardware for the
exact details.
.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
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 CONFIGURATION OF NETWORK PACKET FILTERING
The network packet filtering rules are managed by the
.Sy iptables
service, which needs to be restarted so that the changes in the
.Pa iptables
file can take effect.
.Bd -literal -offset indent
# rc-service iptables restart
.Ed
.Pp
The active set of rules can be queried by the following command.
.Bd -literal -offset indent
# iptables -L -n
.Ed
.Pp
Rules can be dynamically added, deleted, inserted, replaced, and
flushed through the corresponding commands of the
.Sy iptables
utility, see its documentation for the details.  The current state of
the configuration can be recorded by dumping it to temporary file
under a directory which is shared with the host, that is
.Pa /var/tmp
in this case.
.Bd -literal -offset indent
# iptables-save > /var/tmp/iptables
.Ed
.Pp
The file exported this way could be then used as the main
configuration by moving it to the location from where the
.Pa /media/etc
directory is mounted.
.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 (AMD RZ608 Wi-Fi 6E)
.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 CAVEATS
Certain vendors may assign different PCI IDs for their rebranded
products even if they ship exactly the same chipset.  For example, AMD
RZ608 is technically the same as MediaTek MT7921, but its PCI ID had
to be explictly added for the corresponding driver to make it work.
Similar situations may occur any time, please let us know if this
happens.
.Sh SEE ALSO
.Xr wifibox 8 ,
.Xr wpa_supplicant.conf 5 ,
.Xr hostapd.conf 5
.Sh AUTHORS
.An Gábor Páli Aq Mt pali.gabor@gmail.com