Translation(s): none
The Debian /usr Merge
This page tracks Debian support for the merged /usr directories scheme, i.e. the /{bin,sbin,lib}/ directories becoming symbolic links to /usr/{bin,sbin,lib}/.
The usrmerge package will convert the system it is installed on.
For users
You may arrive to this page after seeing this error in apt:
Preparing to unpack .../base-files_13.4_amd64.deb ... ************************************************************************* * * The base-files package cannot be installed because * /bin is a directory, but should be a symbolic link. * * Please install the usrmerge package to convert this system to merged-/usr. * * For more information please read https://wiki.debian.org/UsrMerge. * *************************************************************************
The best explanation of this can be found in the Debian 12 "Bookworm" release notes: https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information.en.html#a-merged-usr-is-now-required
Further documentation will eventually be published in the Debian 13 "Trixie" release notes in 2025.
Resources for developers
Status of the file move moratorium
In the second decision of the CTTE on merged-/usr, it also recommended not moving files between / and /usr. This recommendation is called the file move moratorium. It has since been repealed and delegated to this page. We now encourage moves, subject to caveats below.
Current rules:
Do not move files from /usr to /:
We want /bin, /lib and /sbin to become empty. The direction of move is the wrong one.
Do not add new files into /bin, /lib, /sbin.
- All packages containing diverted files or adding diversions should have their upgrades tested. Most have already been moved and the remaining ones have received patches. When in doubt, please request help.
Transitively essential packages and Priority: required packages must extensively test moving files from / to /usr.
These packages are relevant to filesystem bootstrap and need to work with debootstrap, cdebootstrap and mmdebstrap all of which work subtly different until we finish the move. Also bullseye still has debootstrap that merges in a different way but is being updated via o-p-u.
systemd units and udev rules must be moved from /lib to /usr/lib in all packages (including essential and required):
dh_installsystemd generates maintainer scripts for systemd units below /usr/lib since version 13.11.6. Please add Build-Depends: debhelper (>= 13.11.6)
Any debian/*.service and debian/*.udev files are now installed to /usr/lib. Your next upload will move them automatically.
Any units installed by an upstream build system to systemd_system_unit_dir as discovered using pkgconf will already install into /usr/lib. If you use this variable, ensure that you do not hard code /lib/systemd/system in debian/*.install files.
Any files installed by an upstream build system to udevdir from udev.pc will already into /usr/lib. Again, do not hardcode /lib/udev in debian/*.install files.
Upload restructuring changes to experimental first and wait three days:
Doing so gives the dumat service an opportunity to file a bug in case your change causes one of the problems from DEP17.
This only applies if the restructured package installed to /bin, /lib or /sbin in bookworm or trixie.
Do not update calls to update-alternatives:
Even if you move e.g. /bin/more to /usr/bin/more, do not change the location used in the update-alternatives invocation. The paths passed to update-alternatives are API and changing them would break API. Changing them would also be prone to loss of user preference.
If you add new alternatives, install them to /usr if possible.
Build daemons are /usr-merged since 2023-10-09.
The debian-installer is /usr-merged in git and the archive copy will be on the next upload.
How to move files from / to /usr?
For a lot of packages (about 500 source packages), the only affected files is systemd units. These will be automatically moved via changes in debhelper and systemd.pc. As of now debhelper will install units below /usr and systemd.pc will follow on 2023-11-30. A simple no-change upload or binNMU moves your units. If this applies to you, you may skip over most of this section, but still pay attention to the last paragraph.
Before moving files, please keep in mind that no bookworm suite (and that includes bookworm-backports) should move files to avoid breakage there. So when you look into moving files, the first question to ask is whether you want to support uploads of your package to bookworm-backports. If you do, your packaging should ensure that files continue to be distributed to / and /usr in the same way that they used to be in bookworm. Before dh_installdeb, you may insert dh_movetousr or Build-Depends: dh-sequence-movetousr. This helper is available in bookworm-backports and becomes a no-op there. That said, dh_movetousr is not meant to stay. It encourages maintaining code that becomes dead before too long. If you end up using it, be prepared to remove its use during the forky cycle. If you also want to support backports to bullseye-backports-sloppy, use if command -v dh_movetousr >/dev/null; then dh_movetousr; fi.
If you have aliased systemd units that are manually installed, consider letting dh_installsystemd install them as it will also undo the move in bookworm-backports. In 3.0 source package, debian/somepkge.service may be a symbolic link pointing at location in the upstream source and will correctly be installed.
If you do not want to support uploads to bookworm-related suites such as bookworm-backports, manually moving the files may provide a simplification in packaging. Sometimes, it amounts to removing an existing --prefix=/ and reverting to the default --prefix=/usr. Often times, a package's files have been split to / and /usr in a manual way and this can now be removed. When you do, please check all debian/*.install, debian/*.links and debian/*.dirs files and review that your package does not contain an empty /bin, /lib or /sbin directory.
Regardless of how you perform the move, please upload to experimental. A tool called dumat will analyze your package for some classes of known problems and shall get back to you within three days via the bug tracking system in the event of problems. DEP17 provides a collection of known problem classes. Of these, dumat will check for P1, P2, P3 (mostly), P6, and P7. Problems P8, P9 and P10 are mostly relevant to packages close to the essential set. Affected packages have received instructions or patches. When in doubt, consider asking Helmut. Please check for the following problems before your upload:
P3: Does your package employ non-default diversions? If you unconditionally use dpkg-divert, dumat shall notice. It may fail to notice non-default diversions behind e.g. debconf questions. If those diversions interact with aliased locations, action is needed. Please get in touch with Helmut.
P4: Even when changing all aliased paths from / to /usr, you must not change the paths passed to update-alternatives invocations that already existed in bookworm. The current plan is to keep existing alternatives aliased as a legacy forever and add new alternatives without aliasing.
P5: If your package uses dpkg-statoverride, the paths may have to be updated. The old statoverride should be removed and the new one should be added.
P7: While Multi-Arch: same shared file loss is detected by dumat, you may mitigate it immediately. If affected, the dumat.yaml report shall contain a "risky m-a:same shared file". Chris Hofstaedtler wrote an example to copy from.
In general, we try to handle the more complex cases by sending patches.
After having successfully moved files from / to /usr, there is one more task. Any restructuring change to your package during the trixie cycle should be uploaded to experimental with a three day grace period to detect problems. A restructuring change is renaming a package (for instance adding a t64 suffix for the 2038 transition) or moving a file from one binary package to a different binary package (from the same source package or a different source package).
Can I simply move systemd units to /usr/lib/systemd even in older releases?
Unfortunately, no. If the unit existed earlier in /lib/systemd, moving it to /usr/lib/systemd is prone to loss. So please do not move units from in a backport or stable update. For another dh_installsystemd generates maintainer scripts for installed units. Before trixie it only generates maintainer scripts for units installed to /lib/systemd and not for units installed to /usr/lib/systemd.
Transition priorities
This section is for people working on the transition beyond their own packages. We have a few areas of work.
Important packages and filesystem bootstrap
The target of this work is to get the aliasing symlinks into base-files. To get there we first have to move files in most important packages. Once only the exception are left, there will be a coordinated upload. This work is coordinated with Helmut Grohne and has high risk of fallout. Please refrain from uncoordinated uploads. The intention is to finish this by the end of March 2024.
udev
The moving of udev rules turns out to affect rather more packages. Therefore, dh_installudev and udev.pc now point below /usr, but a lot of packages hardcode the old paths. Patches are being sent to update these packages, but please also work on this directly in the packages you are maintaining. At a later time, binNMUs or new uploads will convert the remaining udev locations.
Previously, some packages would encounter M-A:same shared file loss (P7), but these have been fixed in the meantime.
diversion mitigation
It turned out that the initial version of M18 did not work at all. We are developing a new one on molly-guard. Until this is validated, we should not touch further diversions as we cannot ensure to fix them in a timely manner. This work is driven by Helmut Grohne.
Move files to /usr in other packages
In effect, this is working on the long-tail of the transition and both serves reducing the size of the transition and in discovering unforeseen problems sooner rather than later. So just converting random packages and figuring out how that does not work is a useful thing to do at this time. This is not coordinated. Please report problems to Helmut Grohne. The intention is to finish this by the start of the transition freeze.
FAQ
For more information, please refer to the usrmerge package FAQ, another highly recommended read is <20181121140542.GA31273@espresso.pseudorandom.co.uk>
Is this about merging /usr/bin/ and /usr/sbin/?
No, there are no plans to do that.
Will switching to a merged /usr be mandatory?
In February 2021, the Technical Committee has resolved that Debian 'bookworm' should support only the merged-usr root filesystem layout, dropping support for the non-merged-usr layout. (978636)
The transition started on September 17th, 2022, by making init-system-helpers depend on usrmerge.
usrmerge is uninstallable, what do I do?
You might have run a script that installs a blocker metapackage. It needs to be removed manually, then apt will be able to upgrade the system:
# apt install usrmerge Reading package lists... Done Building dependency tree... Done Reading state information... Done Some packages could not be installed. This may mean that you have requested an impossible situation or if you are using the unstable distribution that some required packages have not yet been created or been moved out of Incoming. The following information may help to resolve the situation: The following packages have unmet dependencies: dpkg-fsys-usrunmess : Conflicts: usrmerge E: Error, pkgProblemResolver::Resolve generated breaks, this may be caused by held packages. # dpkg --remove --force-all dpkg-fsys-usrunmess dpkg: warning: overriding problem because --force enabled: dpkg: warning: this is a protected package; it should not be removed (Reading database ... 26987 files and directories currently installed.) Removing dpkg-fsys-usrunmess (1.21.9) ... # apt install usrmerge Reading package lists... Done Building dependency tree... Done Reading state information... Done The following NEW packages will be installed: usrmerge 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded. Need to get 13.0 kB of archives. After this operation, 39.9 kB of additional disk space will be used. Get:1 http://deb.debian.org/debian sid/main amd64 usrmerge all 31 [13.0 kB] Fetched 13.0 kB in 0s (264 kB/s) debconf: delaying package configuration, since apt-utils is not installed Selecting previously unselected package usrmerge. (Reading database ... 26988 files and directories currently installed.) Preparing to unpack .../archives/usrmerge_31_all.deb ... Unpacking usrmerge (31) ... Setting up usrmerge (31) ... The system has been successfully converted.
Adoption rate
debootstrap has supported a --merged-usr option since version 1.0.83, and this has been the default since version 1.0.85. The default was reverted in 1.0.87 and re-enabled in 1.0.102. A --no-merged-usr option is also available.
See popcon for upgrades of older systems.
Affected packages using dpkg-statoverride
Querying statoverride on path in /bin:
- fuse
- fuse3
- ntfs-3g
Querying and managing statoverride on path in /sbin:
- yp-tools
Developer Links
https://subdivi.de/~helmut/dumat.yaml Current dumat output, but note that you should automatically get bugs if your packages are affected
User-tagged bugs: