.Dd March 13, 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
Alpine Linux is an actively maintained, security-oriented, lightweight
Linux distribution that is 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:
.Bl -bullet
.It
Alpine Linux:
.ft B
https://alpinelinux.org/
.ft R
.It
BusyBox:
.ft B
https://busybox.net/
.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.  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.  This
prevents the guest from damaging the system files on sudden shutdowns,
which may occur due to short and strict time limits placed on the
spin-down sequence.
.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.
.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 .
.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.
.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 SEE ALSO
.Xr wifibox 8
.Sh AUTHORS
.An Gábor Páli Aq Mt pali.gabor@gmail.com