Small. Simple. Secure.

The Alpine Linux Technical Steering Committee (TSC) has decided to change the base filesystem hierarchy. In the future, /lib, /bin, and /sbin will be symbolic links to their /usr counterparts, and every package shall be installed under the /usr paths. For now, /usr/bin and /usr/sbin will continue to be independent paths, but that might change if the Filesystem Hierarchy Standard (FHS) gets updated.

Timeline

The transition to the /usr merge will be organised around 3 milestones:

1. Finish preparations: the preparations that have been in the works for months will be finished, and the Merge Request that finalizes the initial work will be merged. Any new edge installations will be /usr-merged from this point onwards.

2. Release of Alpine Linux 3.23: any new alpine installations of this and future releases will be /usr-merged. Users will be able to upgrade from older releases to 3.23 without being forced to /usr merge their systems, or the /usr-merge causing breakage. From this point onwards, users are encouraged to migrate existing installs.

3. End-of-support for 3.22: after 3.22 is EOL non-/usr-merged systems will be considered officially unsupported. The following stable release (possibly 3.26 or 3.27) will make the /usr-merge compulsory and non-merged installations upgrading to it will break.

How to migrate?

If you are using diskless installations and relying on apkovl files to persist configuration across reboots, you do not need to do anything. The versions of alpine-conf and alpine-mkinitfs available in the 3.23 release correctly unpack the apkovl files on a system with the links in place.

If you have a long-living installation of Alpine Linux edge, or upgraded to 3.23 from an older release, you are encouraged test and migrate your system to be /usr-merged. The /usr-merged system will be better supported in the future, and will be safer to run. To migrate:

• Make sure you have a complete up-to-date system: doas apk upgrade -aU
• Install the transitioning script: doas apk add merge-usr
• Do a “dryrun” of the merging. If any errors are printed out, please open an issue in https://gitlab.alpinelinux.org/alpine/aports/–/issues/new : doas merge-usr --dryrun
• WARNING: Only run this step if the previous step succeeded. Do the merge: doas merge-usr
• Cleanup the transitioning script, not needed anymore: doas apk del merge-usr

Does this affect me?

As a general user, this change should not affect you in any way. The symbolic links warrant backwards compatibility, and PATH will not change, so everything will continue working as it used to. There might be, however, some small group of users affected by this change:

• People making heavy use of apk audit --full functionality and the protected_paths feature. Once the symlinks are in place, things that during the transitional period install under /lib, /bin, or /sbin will produce false-positives due to apk finding them in /usr. For this reason, any usage of /lib, /bin, or /sbin withing protected_paths should be moved to the /usr counterparts.

• Users which have manually installed anything under /lib, /bin, or /sbin might have trouble with the new update. Those paths were never meant to have binaries managed by the system administrator (FHS defines /usr/local for that purpose), so it could be considered an unsupported configuration. The migration should move those files automatically to their /usr counterparts, but it might not be throughly tested.

• Users with / and /usr in different partitions. Once the /usr merge is implemented, / may not contain the executables necessary to mount /usr. Since version 3.21, Alpine’s mkinitfs mounts /usr directly from the initramfs. Make sure you modify your configuration so that the modules required to mount /usr are present in the initramfs.

• Users with their own package repositories, that might still use /lib, /bin or /sbin, and relative symlinks. Systems with such packages installed might break after the /usr merge is implemented. Please make sure that any 3rd party packages you have installed (if you have any) don’t install files to /lib, /bin or /sbin. abuild will already warn if doing otherwise, and will error-out in the future.

Why has this been done?

This has been done for 2 different sets of reasons:

Reasons

There are some potential benefits for Alpine from having installations /usr-merged:

• Reduce packaging maintenance: busybox symlinks and the applications they override do not always agree on the installation location. Moreover, those installation locations might change over time. Through this effort, the postmarketOS team has indeed fixed dozens of occurrences where installations would have two binaries for the same package: one by busybox in /bin or /sbin, and one by another package under /usr.
• The /usr-merged setup is the standard in most of the Linux ecosystem. Many maintainers might not test or support non-/usr-merge filesystems, resulting in additional maintenance for the Alpine Linux team.
• Containerize more distribution-provided data under /usr: making it easier to split the user-owned data from / to the distribution-provided data in /usr. Although not perfect, this makes it easier to do things like rebuilding /usr, backup the system configuration, and potentially mount /usr read-only.

FAQ

• Q: The /bin and /lib directories were a helpful recovery environment.

• A: The historical reasons for the split /usr were to have a recovery environment if the second disk (containing the /usr directory) failed to boot. However, Linux distributions, including Alpine Linux, are using an initramfs which already boots up a minimal environment and with which the rest of the system will be booted.

• Q: Does the /usr merge not make the file hierachy and packaging more complicated?

• A: No, exactly the opposite. As a result of the /usr merge there is only a single location for the distribution to install executables and libraries.