NAME

INTRODUCTION

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:

• Alpine Linux: https://alpinelinux.org/
• BusyBox: https://busybox.net/

IMPLEMENTATION

Although the root user possesses unlimited access to every resource inside the guest, files cannot be changed immediately. Before any administrative operation, the root file system needs to be remounted in writeable mode.

# mount -o remount,rw /

That is because the guest 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, and lack of journaling enabled.

For the same reasons, it is recommended to restore the original mounting strategy once all the changes have been made on the guest.

# mount -o remount,ro /

For the ease of management, the host shares configuration files with the services that are responsible for implementing the domain logic.

• wpa_supplicant works with the 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.
• ifup and ifdown work with the interfaces.conf file to associate the internal network interfaces with IP addresses: wlan0 is the wireless device which is automatically configured through DHCP, eth0 is the virtual Ethernet device which is configured according to the contents of the configuration file.
• udhcpd works with the udhcpd.conf file and implements a DHCP server for 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.
• wpa_passthru works with the wpa_ctrl.conf file that is shared with the host and manages the forwarding of control sockets created for wpa_supplicant. When enabled, it attemps to parse the contents of wpa_supplicant.conf to learn if there are sockets available and exposes them over the configured TCP ports with the help of socat.

The generic configuration files are read from the /media/etc directory where the config 9P (VirtFS) share is mounted in read-only mode. From there, the files are hooked up in the system in the following ways.

• /media/etc/interfaces.conf is mapped to /etc/network/interfaces.conf which is included as part of /etc/network/interfaces when managed by ifup and ifdown.
• /media/etc/udhcpd.conf is mapped to /etc/udhcpd.conf where udhcpd will read its contents.
• /media/etc/wpa_ctrl.conf is not mapped to anywhere under /etc, it is used directly from there by wpa_passthru.

The wpa_supplicant.conf configuration file is shared with the host through the /media/wpa directory where the wpa_config 9P (VirtFS) share is mounted. This will let wpa_supplicant change the contents when instructed to do so from the host through the forwarded control sockets and permitted by the configuration.

The variable data files under the guest's /var directory are shared with the host by mounting the var 9P (VirtFS) share there. This includes streaming out all the logs under the /var/log directory, such as /var/log/dmesg or /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 /var/run directory will not be visible on the host, as it is stored only in the memory.

STARTING, STOPPING, AND RESTARTING SERVICES

# rc-service --list

The status of a specific service can be queried by the status command. For example, the wpa_supplicant tool has its own associated service and it can be checked by the following command.

# rc-service wpa_supplicant status

Similary to this, the start, stop, and 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 networking service.

# rc-service networking restart

These commands can help with troubleshooting and restoring the respective services in case of failures.

RESIZING THE FILE SYSTEM

Such operations must always be considered on two levels: the size of the disk image needs to be changed on the host, and the size of the file system needs to be changed on the guest. The order of the corresponding commands must always reflect the direction of the change in size to avoid losing data.

For growing the root file system, increase the size of the disk image to the desired capacity with the truncate(1) utility. For example, consider extending the virtual disk to 1 gigabyte.

# truncate -s 1G disk.img

The guest has to be restarted to notice the change in the disk parameters.

# wifibox restart guest

Once the restart operation completed, the interactive cfdisk utility on the guest can be used to resize the partition of the root file system, /dev/vda1.

# cfdisk

The resize2fs utility on the guest supports growing the root file system while it is in use, however it must be mounted writable first. The command will automatically extends the file system's size to match with the size of the corresponding partition, which has been grown in the previous step. After completion, the file system is ready for use.

# mount -o remount,rw /
# resize2fs /dev/vda1

For shrinking the root file system, the size of the root file system has to be decreased first. This can be implemented by the resize2fs utility, but it supports shrinking only when the underlying file system is not mounted. In case of the root file system a way to achieve this is to mirror its contents in the memory and trigger all the processes to re-load themselves from there. That is why this operation requires the guest to be configured with more memory, e.g. 1 GB, otherwise it may fail.

Through the following set of commands, a tmpfs-backed file system is created and populated with the contents of the root so it could take over its place in the next steps.

mkdir /tmp/tmproot
mount -t tmpfs tmpfs /tmp/tmproot
for dir in oldroot dev proc sys run tmp boot; do \
  mkdir /tmp/tmproot/$dir; done
for dir in bin etc home lib media mnt opt root sbin srv usr var; do \
  cp -a /$dir /tmp/tmproot/$dir; done

Then the pivot_root and mount commands are employed to switch to the freshly built root file system and migrate all the existing mount points there. The previous root file system becomes available under the path /oldroot.

cd /tmp/tmproot
pivot_root . oldroot
for dir in boot dev proc run sys media/etc media/var; do \
  mount --move /oldroot/$dir /$dir; done
mount -t tmpfs tmpfs /tmp

Since all the services, including the init process with PID 1, have been launched from the old root, init must be told to restart itself by sending the QUIT signal. In consequence, all the other services will also be restarted and the user is logged out.

# kill -QUIT 1

Login and restart the networking service to restore the network connection to the outside world.

# rc-service networking restart

Now it should be possible to detach the old root file system.

# umount /oldroot

In case this previous command fails, it is recommended to use the fuser utility to obtain the list of processes, by their IDs, that keep files open on the file system.

# fuser -m /oldroot

If the old root file system has been successfully unmounted, it must be checked for errors first and it must be marked clean, otherwise resize2fs refuses to modify it. Then the resize2fs command could be called with the -M flag that shrinks the file system to the smallest possible size that is considered safe to use.

# e2fsck -f /dev/vda1
# resize2fs -M /dev/vda1

After the successful shrinking of the file system, the cfdisk utility can be launched to decrease the size of the corresponding partition so that the overall size of the disk image could be made smaller. The size of the partition has to match with the size of the contained file system. That latter can be queried with using the dumpe2fs tool, in the following way for instance.

# dumpe2fs -h /dev/vda1 | fgrep "Block count:" | cut -c27-

This value has to be multipled by 8 to get the number of sectors for the new partition size. This ratio comes from the difference of file system block size, which is 4096 bytes, and the sector size, which is 512 bytes. Once this is learnt, cfdisk could be launched to shrink the partition. Remember to use S as the unit of measure.

# cfdisk

Before leaving the cfdisk utility, take a note on the start sector of the free space after the resized partition because that shall indicate the new size of the disk image. Multiply this number with the size of the sectors, which is 512 bytes, to get the value to be passed for the truncate(1) command for trimming the image. In the following example, the free space started at sector 745472.

# truncate -s `expr 745472 \* 512` disk.img

Restore the guest memory to the standard setting and restart the guest to make it pick up the changes in the disk parameters, also to give back the extra memory to the host.

# wifibox restart guest

INSTALLING OR REMOVING PACKAGES

# apk list --installed

Note that the amount of memory configured for the guest might not be enough for the next steps. Raise it to around 128 MB if it has not been set like that already.

Once prepared, it is possible to proceed with getting the latest version of the database. The apk tool stores the list of currently used package repositories in the /etc/apk/repositories file.

# apk update

Individual packages can be then installed by the add command, assuming that they are available. For example, in case of the wireless-tools package, this works as follows:

# apk add wireless-tools

The unneeded packages can be removed by the del command.

# apk del wireless-tools

PERFORMING UPGRADES

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 /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 apk may report an untrusted signature due to lack of the necessary certificates to verify the fresh ones.

As soon as everything is properly prepared, refresh the package index.

# apk update

The system can be then upgraded in a single step by using the upgrade command.

# apk upgrade --available

Restart the guest for these changes to take effect, especially if the kernel or the firmware files received an update.

# wifibox restart guest

CAVEATS

SEE ALSO

AUTHORS