Add manual page.

1 files changed, 269 insertions, 0 deletions

diff --git a/man/wifibox-alpine.5 b/man/wifibox-alpine.5
new file mode 100644
index 0000000..6c938ca
--- /dev/null
+++ b/man/wifibox-alpine.5
@@ -0,0 +1,269 @@
+.Dd February 18, 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
+By default, 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 from there.  That is because the operating
+system is built in a way that it does not normally 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.
+.El
+.Pp
+The 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/wpa_supplicant.conf
+is mapped to
+.Pa /etc/wpa_supplicant/wpa_supplicant.conf
+where
+.Sy wpa_supplicant
+will read its contents.
+.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.
+.El
+.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 under the standard
+.Pa /var
+directory.  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.
+.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 MANAGING THE ROOT FILE SYSTEM
+When changing the contents of the guest's root file system is desired,
+it may be accessed from the host directly.  It is shared via 9P
+(VirtFS), which means that the files are visible and modifiable
+through the host.  But because it still features Linux binaries, use
+of the
+.Xr chroot 8
+command is recommended to launch a Linux-based shell (i.e. BusyBox)
+inside the directory that holds the guest root file system on the
+host.
+.Bd -literal -offset indent
+# chroot %%ROOT%% /bin/ash
+.Ed
+.Pp
+For the rest of this document, the commands are discussed in such an
+environment, unless stated otherwise.
+.Sh INSTALLING OR REMOVING PACKAGES
+The list of installed packages can be queried by the
+.Sy apk
+(Alpine Package Keeper) tool.  This tool is going to be used for the
+rest of the section.
+.Bd -literal -offset indent
+# apk list --installed
+.Ed
+.Pp
+Before installing any package, it is recommended to get the latest
+version of the database.  The
+.Sy apk
+tool stores the list of currently used package repositories in the
+.Pa /etc/apk/repositories
+file.
+.Bd -literal -offset indent
+# apk update
+.Ed
+.Pp
+Individual packages can be then installed by the
+.Cm add
+command, assuming that they are available.  For example, in case of
+the
+.Sy wireless-tools
+package, this works as follows:
+.Bd -literal -offset indent
+# apk add wireless-tools
+.Ed
+.Pp
+The unneeded packages can be removed by the
+.Cm del
+command.
+.Bd -literal -offset indent
+# apk del wireless-tools
+.Ed
+.Sh PERFORMING UPGRADES
+It is possible to upgrade the operating system running on the guest to
+receive fixes for the kernel, drivers, and the userland programs.  The
+entire process can be managed with the help of the
+.Sy apk
+tool.
+.Pp
+First make sure that the local package database is brought in sync
+with latest versions of the configured repositories.  This can be
+verified by checking that the proper version numbers are used in the
+.Pa /etc/apk/repositories
+file.  In addition to this, before moving between major or minor
+versions, e.g. from Alpine Linux 3.14 to 3.15, it is important to
+ensure that the system is on the latest available version for the
+current branch, and then try to pull the package index for the next
+major or minor version.  That is required otherwise
+.Sy apk
+may report an untrusted signature due to lack of the necessary
+certificates to verify the fresh ones.
+.Pp
+As soon as everything is properly prepared, refresh the package index.
+.Bd -literal -offset indent
+# apk update
+.Ed
+.Pp
+The system can be then upgraded in a single step by using the
+.Cm upgrade
+command.
+.Bd -literal -offset indent
+# apk upgrade --available
+.Ed
+.Pp
+Restart the guest for these changes to take effect by issuing the
+following command on the host.  Note that one can get back to the host
+system by exiting the shell, e.g. by the
+.Cm exit
+command.
+.Bd -literal -offset indent
+# wifibox restart guest
+.Ed
+.Sh CAVEATS
+Custom modifications to the guest file system are not supported.  Use
+the respective commands at your own risk!
+.Sh SEE ALSO
+.Xr wifibox 8 ,
+.Xr chroot 8
+.Sh AUTHORS
+.An Gábor Páli Aq Mt pali.gabor@gmail.com