Chapter 5. Issues to be aware of for bookworm

As described in Section 2.2, “Archive areas”, non-free firmware packages are now served from a dedicated archive component, called non-free-firmware. To ensure installed non-free firmware packages receive proper upgrades, changes to the APT configuration are required. Assuming the non-free component was only added to the APT sources-list to install firmware, the updated APT source-list entry could look like:

deb https://deb.debian.org/debian bookworm main non-free-firmware

If you were pointed to this chapter by apt you can prevent it from continuously notifying you about this change by creating an apt.conf(5) file named /etc/apt/apt.conf.d/no-bookworm-firmware.conf with the following content:

APT::Get::Update::SourceListWarnings::NonFreeFirmware "false";

The ntp package, which used to be the default way to set the system clock from a Network Time Protocol (NTP) server, has been replaced by ntpsec.

Most users will not need to take any specific action to transition from ntp to ntpsec.

In bookworm there are also several other packages that provide a similar service. The Debian default is now systemd-timesyncd, which may be adequate for users who only need an ntp client to set their clock. bookworm also includes chrony and openntpd which support more advanced features, such as operating your own NTP server.

Puppet has been upgraded from 5 to 7, skipping the Puppet 6 series altogether. This introduces major changes to the Puppet ecosystem.

The classic Ruby-based Puppet Master 5.5.x application has been deprecated upstream and is no longer available in Debian. It is replaced by Puppet Server 7.x, provided by the puppetserver package. The package is automatically installed as a dependency of the transitional puppet-master package.

In some cases, Puppet Server is a drop-in replacement for Puppet Master, but you should review the configuration files available under /etc/puppet/puppetserver to ensure the new defaults are suitable for your deployment. In particular the legacy format for the auth.conf file is deprecated, see the auth.conf documentation for details.

The recommended approach is to upgrade the server before clients. The Puppet 7 Server is backwards compatible with older clients; a Puppet 5 Server can still handle upgraded agents but cannot register new Puppet 7 agents. So if you deploy new Puppet 7 agents before upgrading the server, you will not be able to add them to the fleet.

The puppet package has been replaced by the puppet-agent package and is now a transitional package to ensure a smooth upgrade.

Finally, the puppetdb package was removed in bullseye but is reintroduced in bookworm.

The popular tool youtube-dl, which can download videos from a large variety of websites (including, but not limited to, YouTube) is no longer included in Debian. Instead, it has been replaced with an empty transitional package that pulls in the yt-dlp package instead. yt-dlp is a fork of youtube-dl where new development is currently happening.

There are no compatibility wrappers provided, so you'll need to modify your scripts and personal behavior to call yt-dlp instead of youtube-dl. The functionality should be mostly the same, although some options and behavioral details have changed. Be sure to check yt-dlp's man page for details, and in particular the Differences in default behavior section.

The packages fcitx and fcitx5 provide version 4 and version 5 of the popular Fcitx Input Method Framework. Following upstream's recommendation, they can no longer be co-installed on the same operating system. Users should determine which version of Fcitx is to be kept if they had co-installed fcitx and fcitx5 previously.

Before the upgrade, users are strongly encouraged to purge all related packages for the unwanted Fcitx version (fcitx-* for Fcitx 4, and fcitx5-* for Fcitx 5). When the upgrade is finished, consider executing the im-config again to select the desired input method framework to be used in the system.

You can read more background information in the announcement posted in the mailing list (text written in Simplified Chinese).

Unlike bullseye that had the MariaDB version in package names (e.g. mariadb-server-10.5 and mariadb-client-10.5), in bookworm the equivalent MariaDB 10.11 package names are fully versionless (e.g. mariadb-server or mariadb-client). The MariaDB version is still visible in the package version metadata.

There is at least one known upgrade scenario (Bug #1035949) where the transition to versionless package names fails: running

apt-get install default-mysql-server

may fail when mariadb-client-10.5 and the file /usr/bin/mariadb-admin in it is removed before the MariaDB server SysV init service has issued a shutdown, which uses mariadb-admin. The workaround is to run

apt upgrade

before running

apt full-upgrade

.

For more information about the package name changes in MariaDB, see /usr/share/doc/mariadb-server/NEWS.Debian.gz.

The rsyslog package is no longer needed on most systems and you may be able to remove it.

Many programs produce log messages to inform the user of what they are doing. These messages can be managed by systemd's “journal” or by a “syslog daemon” such as rsyslog.

In bullseye, rsyslog was installed by default and the systemd journal was configured to forward log messages to rsyslog, which writes messages into various text files such as /var/log/syslog.

From bookworm, rsyslog is no longer installed by default. If you do not want to continue using rsyslog, after the upgrade you can mark it as automatically installed with

apt-mark auto rsyslog

and then an

apt autoremove

will remove it, if possible. If you have upgraded from older Debian releases, and not accepted the default configuration settings, the journal may not have been configured to save messages to persistent storage: instructions for enabling this are in journald.conf(5).

If you decide to switch away from rsyslog you can use the journalctl command to read log messages, which are stored in a binary format under /var/log/journal. For example,

journalctl -e

shows the most recent log messages in the journal and

journalctl -ef

shows new messages as they are written (similar to running

tail -f /var/log/syslog

).

rsyslog now defaults to “high precision timestamps” which may affect other programs that analyze the system logs. There is further information about how to customize this setting in rsyslog.conf(5).

The change in timestamps may require locally-created logcheck rules to be updated. logcheck checks messages in the system log (produced by systemd-journald or rsyslog) against a customizable database of regular expressions known as rules. Rules that match the time the message was produced will need to be updated to match the new rsyslog format. The default rules, which are provided by the logcheck-database package, have been updated, but other rules, including those created locally, may require updating to recognize the new format. See /usr/share/doc/logcheck-database/NEWS.Debian.gz for a script to help update local logcheck rules.

rsyslog has changed which log files it creates, and some files in /var/log can be deleted.

If you are continuing to use rsyslog (see Section 5.1.7, “Changes to system logging”), some log files in /var/log will no longer be created by default. The messages that were written to these files are also in /var/log/syslog but are no longer created by default. Everything that used to be written to these files will still be available in /var/log/syslog.

The files that are no longer created are:

OpenLDAP 2.5 is a major new release and includes several incompatible changes as described in the upstream release announcement. Depending on the configuration, the slapd service might remain stopped after the upgrade, until necessary configuration updates are completed.

The following are some of the known incompatible changes:

Instructions for completing the upgrade and resuming the slapd service can be found in /usr/share/doc/slapd/README.Debian.gz. You should also consult the upstream upgrade notes.

For a long time, grub has used the os-prober package to detect other operating systems installed on a computer so that it can add them to the boot menu. Unfortunately, that can be problematic in certain cases (e.g. where guest virtual machines are running), so this has now been disabled by default in the latest upstream release.

If you are using GRUB to boot your system and want to continue to have other operating systems listed on the boot menu, you can change this. Either edit the file /etc/default/grub, ensure you have the setting GRUB_DISABLE_OS_PROBER=false and re-run update-grub, or run

dpkg-reconfigure <GRUB_PACKAGE>

to change this and other GRUB settings in a more user-friendly way.

Many GNOME apps have switched from the GTK3 graphics toolkit to GTK4. Sadly, this has made many apps much less usable with screen readers such as orca.

If you depend on a screen reader you should consider switching to a different desktop such as Mate, which has better accessibility support. You can do this by installing the mate-desktop-environment package. Information about how to use Orca under Mate is available at here.

For consistency with upstream and other distributions, the polkit (formerly PolicyKit) service, which allows unprivileged programs to access privileged system services, has changed the syntax and location for local policy rules. You should now write local rules for customizing the security policy in JavaScript, and place them at /etc/polkit-1/rules.d/*.rules. Example rules using the new format can be found in /usr/share/doc/polkitd/examples/, and polkit(8) has further information.

Previously, rules could be written in pkla format, and placed in subdirectories of /etc/polkit-1/localauthority or /var/lib/polkit-1/localauthority. However, .pkla files should now be considered deprecated, and will only continue to work if the polkitd-pkla package is installed. This package will usually be installed automatically when you upgrade to bookworm, but it is likely not to be included in future Debian releases, so any local policy overrides will need to be migrated to the JavaScript format.

Debian has adopted a filesystem layout, referred to as “merged-/usr”, which no longer includes the legacy directories /bin, /sbin, /lib, or optional variants such as /lib64. In the new layout, the legacy directories are replaced with symlinks to the corresponding locations /usr/bin, /usr/sbin, /usr/lib, and /usr/lib64. This means that, for example, both /bin/bash and /usr/bin/bash will launch bash.

For systems installed as buster or bullseye there will be no change, as the new filesystem layout was already the default in these releases. However, the older layout is no longer supported, and systems using it will be converted to the new layout when they are upgraded to bookworm.

The conversion to the new layout should have no impact on most users. All files are automatically moved to their new locations even if they were installed locally or come from packages not provided by Debian, and hardcoded paths such as /bin/sh continue to work. There are, however, some potential issues:

For further information, see The Case for the /usr merge and the Debian Technical Committee resolution.

Debian officially supports upgrades only from one stable release to the next, e.g. from bullseye to bookworm. Upgrades from buster to bookworm are not supported, and will fail due to Bug #993755 with the following error:

Setting up libc6:armhf (2.36-9) ...
/usr/bin/perl: error while loading shared libraries: libcrypt.so.1: cannot open shared object file: No such file or directory
dpkg: error processing package libc6:armhf (--configure):
installed libc6:armhf package post-installation script subprocess returned error exit status 127
        

It is however possible to manually recover from this particular situation by forcibly installing the new libcrypt1:

# cd $(mktemp -d)
# apt download libcrypt1
# dpkg-deb -x libcrypt1_*.deb .
# cp -ra lib/* /lib/
# apt --fix-broken install
        

When apt full-upgrade has finished, the “formal” upgrade is complete. For the upgrade to bookworm, there are no special actions needed before performing a reboot.

There are some packages where Debian cannot promise to provide minimal backports for security issues. These are covered in the following subsections.

	Note
	The package debian-security-support helps to track the security support status of installed packages.

The Debian provided python3 interpreter packages (python3.11 and pypy3) are now marked as being externally-managed, following PEP-668. The version of python3-pip provided in Debian follows this, and will refuse to manually install packages on Debian's python interpreters, unless the --break-system-packages option is specified.

If you need to install a Python application (or version) that isn't packaged in Debian, we recommend that you install it with pipx (in the pipx Debian package). pipx will set up an environment isolated from other applications and system Python modules, and install the application and its dependencies into that.

If you need to install a Python library module (or version) that isn't packaged in Debian, we recommend installing it into a virtualenv, where possible. You can create virtualenvs with the venv Python stdlib module (in the python3-venv Debian package) or the virtualenv Python 3rd-party tool (in the virtualenv Debian package). For example, instead of running pip install --user foo, run: mkdir -p ~/.venvs && python3 -m venv ~/.venvs/foo && ~/.venvs/foo/bin/python -m pip install foo to install it in a dedicated virtualenv.

See /usr/share/doc/python3.11/README.venv for more details.

The VLC video player supports hardware-accelerated video decoding and encoding via VA-API and VDPAU. However, VLC's support for VA-API is tightly related to the version of FFmpeg. Because FFmpeg was upgraded to the 5.x branch, VLC's VA-API support has been disabled. Users of GPUs with native VA-API support (e.g., Intel and AMD GPUs) may experience high CPU usage during video playback and encoding.

Users of GPUs offering native VDPAU support (e.g., NVIDIA with non-free drivers) are not affected by this issue.

Support for VA-API and VDPAU can be checked with vainfo and vdpauinfo (each provided in a Debian package of the same name).

The new systemd-resolved package will not be installed automatically on upgrades. If you were using the systemd-resolved system service, please install the new package manually after the upgrade, and note that until it has been installed, DNS resolution might no longer work since the service will not be present on the system. Installing this package will automatically give systemd-resolved control of /etc/resolv.conf. For more information about systemd-resolved, consult the official documentation. Note that systemd-resolved was not, and still is not, the default DNS resolver in Debian. If you have not configured your machine to use systemd-resolved as the DNS resolver, no action is required.

The new systemd-boot package will not be installed automatically on upgrades. If you were using systemd-boot, please install this new package manually, and note that until you do so, the older version of systemd-boot will be used as the bootloader. Installing this package will automatically configure systemd-boot as the machine's bootloader. The default boot loader in Debian is still GRUB. If you have not configured the machine to use systemd-boot as the bootloader, no action is required.

The optional systemd-journal-gatewayd and systemd-journal-remote services are now built without GnuTLS support, which means the --trust option is no longer provided by either program, and an error will be raised if it is specified.

There have been several changes in adduser. The most prominent change is that --disabled-password and --disabled-login are now functionally identical. For further details, please read the /usr/share/doc/adduser/NEWS.Debian.gz.

The predictable naming logic in systemd for network interfaces has been extended to generate stable names from Xen netfront device information. This means that instead of the former system of names assigned by the kernel, interfaces now have stable names of the form enX#. Please adapt your system before rebooting after the upgrade. Some more information can be found on the NetworkInterfaceNames wiki page.

dash, which by default provides the system shell /bin/sh in Debian, has switched to treating the circumflex (^) as a literal character, as was always the intended POSIX-compliant behavior. This means that in bookworm [^0-9] no longer means “not 0 to 9” but “0 to 9 and ^”.

The netcat utility for reading and writing data across network connections supports abstract sockets, and uses them by default in some circumstances.

By default, netcat is provided by netcat-traditional. However, if netcat is provided by the netcat-openbsd package and you are using an AF_UNIX socket, then this new default applies. In this case the -U option to nc will now interpret an argument starting with an @ as requesting an abstract socket rather than as a filename beginning with an @ in the current directory. This can have security implications because filesystem permissions can no longer be used to control access to an abstract socket. You can continue to use a filename starting with an @ by prefixing the name with ./ or by specifying an absolute path.

The following is a list of known and noteworthy obsolete packages (see Section 4.8, “Obsolete packages” for a description).

The list of obsolete packages includes:

With the next release of Debian 13 (codenamed trixie) some features will be deprecated. Users will need to migrate to other alternatives to prevent trouble when updating to Debian 13.

This includes the following features: