------------------------------- The Debian Package apt-listbugs ------------------------------- Introduction ============ apt-listbugs is a tool which retrieves bug reports from the Debian Bug Tracking System and lists them. In particular, it is intended to be invoked before each upgrade by apt, or other similar package managers, in order to check whether the upgrade/installation is safe. Most Debian developers, and some users, use the unstable version of Debian, because this version is the latest snapshot which includes many new features and packages. apt is a great and convenient tool to let your system easily track the latest package versions from unstable. On the other hand, this capability can also make your system fragile. If a broken package is uploaded to Debian unstable, the package will soon get installed on many Debian systems. The same reasoning holds for the testing version of Debian, even though to a smaller extent. apt-listbugs can help by warning its users about bugs in packages which are about to be installed/upgraded and by giving the opportunity to avoid or defer an unsafe installation/upgrade. You can easily install apt-listbugs by using apt. Usually, no customization is required. However, the use of a proxy server is recommended, in order to reduce the number of accesses to the BTS. Notes ===== This version of apt-listbugs uses the Debian BTS SOAP interface for bug retrieval. apt-listbugs has a simple built-in interactive viewer. It uses the querybts program as a back-end. To enable this feature, you need to install the reportbug package. In addition, you can select broken packages for pinning, to avoid automatically upgrading them. However, pinning is not effective immediately, and requires restarting your apt session. The pinning will be removed by a cron.daily job, when the bugs no longer affect the candidate version of the package. If you install www-browser, you can view bug lists in HTML. sensible-browser from the sensible-utils package is also available. Need for a controlling terminal (/dev/tty) ========================================== apt-listbugs requires a controlling terminal for user interaction. It will default to non-interactive failure mode if its standard output is not a tty. apt-listbugs will also default to non-interactive failure mode if it cannot open /dev/tty when running under an apt session. This may happen when apt-listbugs is (directly or indirectly) invoked inside su -c "command"; commands invoked this way will have no controlling terminal, because of a security fix applied to the package login from version 1:4.1.5-1 on (see bug #628843). Hence, if you want to use apt-listbugs interactively, please do *not* invoke it (or the package manager that will invoke it) through the su -c "command" mechanism. Also, please note that some package managers (such as aptitude, wajig, and possibly others), when run as a regular user, tend to gain root privileges through the su -c "command" mechanism, for the actions that need these privileges. Hence, if you want to use apt-listbugs interactively, please become root *before* invoking the package manager, as in: $ su - Password: # aptitude rather than: $ aptitude See bug #662983 for more details on this issue. Current Design Limitation ========================= There is a problem with packages which have source-version and binary-version mismatch. The BTS tracks the source version, while apt-listbugs tracks the binary version. This conflict results in version tracking not functioning for such packages. A popular example of such a package is gcc. apt-cacher/apt-cacher-ng and proxy configuration ================================================== When installing apt-cacher or apt-cacher-ng with proxy configuration, you will have configured apt proxy settings to use apt-cacher. apt-listbugs will also use that configuration, and since apt-cacher won't handle POST requests directed to the BTS, it will fail. You will have a configuration like: Acquire::http { Proxy "http://CacheServerIp:3142"; }; for apt-cacher; add a specific proxy configuration line for bugs.debian.org so that apt-listbugs can use a different configuration: Acquire::http::Proxy::bugs.debian.org "DIRECT"; Use of apt-listbugs in unattended installations/upgrades ======================================================== As previously mentioned, apt-listbugs requires a console for user interaction. This could make coexistence with unattended package installations/upgrades (e.g.: see the cron-apt package) a little harder. With its default configuration, apt-listbugs will stop any automatic installation or upgrade, whenever the packages to be installed or upgraded are affected by RC bugs. If this is the desired behavior, no special action is needed; you may safely skip the rest of this section. On the other hand, if you want apt-listbugs to merely show bugs, without stopping the installation/upgrade process, you can obtain this behavior by editing /etc/apt/apt.conf.d/10apt-listbugs to add the "yes" option "-y": the following line DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt || exit 10";}; should become DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs -y apt || exit 10";}; Please note that this configuration could even be made conditional: DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs $APT_LISTBUGS_OPTS apt || exit 10";}; This way, apt-listbugs will avoid stopping the installation/upgrade process *only* if an APT_LISTBUGS_OPTS environment variable is set to "-y". Otherwise, if APT_LISTBUGS_OPTS is unset (or set to a zero-length string), apt-listbugs will behave as usual. However, such a conditional configuration is probably a bit risky, since *anything* could be included (even by mistake) in the APT_LISTBUGS_OPTS environment variable. Why does apt-listbugs ignore the "affects" field? ================================================= Sometimes a bug has an effect on package A, but is actually due to a flaw in package B. The BTS is able to track this kind of situation: the bug report should be assigned to package B (where the bug can actually be fixed), but marked as affecting package A, by using the "affects" BTS command. Nonetheless, apt-listbugs currently ignores the "affects" field. In other words, when examining the bugs of package A, apt-listbugs does not take bugs affecting A into account; it only looks at the bugs actually assigned to A. This is intentional, for the reasons explained below. When a bug is assigned to package B, and found in version b1, but marked as affecting package A, this may correspond to one of two possible scenarios: 0) the bug is actually present in B/b1, but causes breakage in package A; hence, do not upgrade to B/b1 if you want to avoid breaking package A 1) the bug is actually present in B/b1, but only shows up when a given version (say, a1) of package A is installed; hence, do not upgrade to A/a1 if you want to prevent the bug in package B from showing up In scenario 0, we should not stop an upgrade (or an installation) of package A because of the bug that affects A: package B is the only one which is able to introduce the bug into a system. Hence, as long as the bug is correctly assigned to B and marked as found in version b1, apt-listbugs will give users the opportunity to stop an upgrade to B/b1, but, on the other hand, will ignore the bug when upgrading package A. This is obtained by ignoring the "affects" field, which is exactly what apt-listbugs does. In scenario 1, stopping an upgrade to A/a1 would actually be useful, as it would prevent the bug from showing up. However, the "affects" field does not carry any version tracking information, unfortunately. This means that there's no way for apt-listbugs to know that the problematic upgrade is the one to A/a1, rather than to A/a2 or to A/a3. And there's no way for apt-listbugs to distinguish between scenario 0 and scenario 1, either. Hence, apt-listbugs currently ignores the "affects" field in any case. There's a way to work around the lack of version tracking info for the "affects" field: whenever you find yourself in scenario 1, file a dummy bug report against package A, marking it as found in version a1 and as blocked by the actual bug report (the one assigned to package B). Please choose a descriptive bug report title, citing the interaction with package B, in order to let users quickly see whether they should worry about the issue. Anyway, please take into account that this strategy is sub-optimal and may annoy some package maintainers! Everything said so far holds for the apt-listbugs "apt" command. The other apt-listbugs commands ("list" and "rss") need to behave consistently, or otherwise they will produce misleading output. Please note that scenario 1 could be dealt with differently, if the BTS added version tracking info for the "affects" field, or, maybe, if it implemented a distinct way to express scenario 1, so that it's not confused with scenario 0 and has version tracking info. See http://lists.debian.org/debian-devel/2011/10/msg00446.html http://lists.debian.org/debian-devel/2011/10/msg00502.html for more details. If there's consensus on this idea, a wishlist bug report should probably be filed against the debbugs package, requesting this new feature. Debugging and filing bug reports against apt-listbugs ===================================================== When there is an error, to obtain useful debugging information, please run apt-listbugs with the debug option "-d". If the error was encountered when using "apt-listbugs list" or "apt-listbugs rss", just re-run the command-line with the "-d" option added, and attach the output along with your bug report. If the error was encountered when using "apt-listbugs apt" (within an apt session), you may enable debug output by editing /etc/apt/apt.conf.d/10apt-listbugs to add the debug option "-d": the following line DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt || exit 10";}; should become DPkg::Pre-Install-Pkgs {"/usr/sbin/apt-listbugs apt -d || exit 10";}; Then please restart the apt session, and attach the output along with your bug report. Hacking apt-listbugs ==================== There is so much more information about the BTS SOAP interface available from debbugs source: http://bugs.debian.org/debbugs-source/mainline/Debbugs/Bugs.pm