DEBBISECT
Section: User Commands (1)
Updated: October 2023
Index
Return to Main Contents
NAME
debbisect - bisect snapshot.debian.org
DESCRIPTION
usage: debbisect [-h] [-d] [-v] [--cache CACHE] [--nocache] [--port PORT]
-
[--depends DEPENDS] [--qemu QEMU]
[--architecture ARCHITECTURE] [--suite SUITE]
[--components COMPONENTS] [--no-find-exact-package]
[--ignore-cached-results]
good bad script
Execute a script or a shell snippet for a known good timestamp and a known bad
timestamp and then bisect the timestamps until a timestamp from
snapshot.debian.org is found where the script first fails. Environment
variables are used to tell the script which timestamp to test. See ENVIRONMENT
VARIABLES below. At the end of the execution, the files debbisect.log.good and
debbisect.log.bad are the log files of the last good and last bad run,
respectively. By default, a temporary caching mirror is executed to reduce
bandwidth usage on snapshot.debian.org. If you plan to run debbisect multiple
times on a similar range of timestamps, consider setting a non-temporary cache
directory with the --cache option.
The program has three basic modes of operation. In the first, the given script
is responsible to set up everything as needed:
-
$ ./debbisect "last week" today script.sh
$ diff -u debbisect.log.good debbisect.log.bad
If also the --depends option is given, then a chroot of the correct timestamp
will be created each time and the script will receive as first argument the
path to that chroot. Additionally, this mode allows debbisect to figure out the
exact package that was responsible for the failure instead of only presenting
you the last good and first bad timestamp.
Lastly, you can also provide the --qemu option. In this mode, your test will be
create a qemu virtual machine of the correct timestamp each time. The script
will receive the correct ssh config to log into a host named qemu and execute
arbitrary commands.
positional arguments:
- good
-
good timestamp -- see section TIMESTAMPS for valid
formats
- bad
-
bad timestamp -- see section TIMESTAMPS for valid
formats
- script
-
test script -- can either be a shell code snippet or
an executable script. A non zero exit code indicates
failure. When also --depends is used, then the first
argument to the script will be the chroot directory.
When --qemu is used, then the first argument to the
script will an ssh config for a host named qemu.
options:
- -h, --help
-
show this help message and exit
- -d, --debug
-
Print lots of debugging statements
- -v, --verbose
-
Be verbose
- --cache CACHE
-
cache directory -- by default $TMPDIR is used
- --nocache
-
disable cache
- --port PORT
-
manually choose port number for the apt cache instead
of automatically choosing a free port
- --depends DEPENDS
-
Comma separated list of binary packages the test
script requires. With this option, the test script
will run inside a chroot with the requested packages
installed.
- --qemu QEMU
-
Create qemu virtual machine and pass a ssh config file
to the test script. This argument takes a commaseparated series of key=value pairs to specify the
virtual machine memory size (via memsize) and the
virtual machine disksize (via disksize). Sizes are
measured in bytes or with common unit suffixes like M
or G. To pick the default values
(disksize=4G,memsize=1G) the shorthand 'defaults' can
be passed.
- --architecture ARCHITECTURE
-
Chosen architecture when creating the chroot with
--depends or --qemu (default: native architecture)
- --suite SUITE
-
Chosen suite when creating the chroot with --depends
or --qemu (default: unstable)
- --components COMPONENTS
-
Chosen components (separated by comma or whitespace)
when creating the chroot with --depends or --qemu
(default: main)
- --no-find-exact-package
-
Normally, when the --depends argument is given so that
debbisect takes care of managing dependencies, the
precise package that introduced the problem is
determined after bisection by installing the packages
that differ between the last good and first bad
timestamp one by one. This option disables this
feature.
- --ignore-cached-results
-
Perform a run for a timestamp even if a log file for
it exists in the current directory
TIMESTAMPS
Valid good and bad timestamp formats are either:
-
> the format used by snapshot.debian.org
> ISO 8601 (with or without time, seconds and timezone)
> RFC 2822 (used in debian/changelog)
> all formats understood by the Python dateutil module (if installed)
> all formats understood by the Python parsedatetime module (if installed)
Without specifying the timezone explicitly, the local offset is used.
Examples (corresponding to the items in above list, respectively):
-
> 20200313T065326Z
> 2020-03-13T06:53:26+00:00
> Fri, 29 Nov 2019 14:00:08 +0100
> 5:50 A.M. on June 13, 1990
> two weeks ago
The earliest timestamp that works with debbisect should be 2006-08-10.
ENVIRONMENT VARIABLES
The following environment variables are available to the test script:
DEBIAN_BISECT_MIRROR Contains the caching mirror address.
DEBIAN_BISECT_EPOCH Contains an integer representing the unix epoch of the
- current timestamp. The value of this variable can
-
directly be assigned to SOURCE_DATE_EPOCH.
DEBIAN_BISECT_TIMESTAMP Contains a timestamp in the format used by
- snapshot.debian.org. Can also be generated from
-
DEBIAN_BISECT_EPOCH via:
date --utc --date=@$DEBIAN_BISECT_EPOCH +%Y%m%dT%H%M%SZ
DEBIAN_BISECT_* All environment variables starting with DEBIAN_BISECT_
-
are passed to the test script.
EXAMPLES
Just run "do_something" which runs the test and returns a non-zero exit on
failure.
-
$ ./debbisect "last week" today "mmdebstrap --customize-hook='chroot \"\$1\" do_something' unstable - \$DEBIAN_BISECT_MIRROR >/dev/null"
$ diff -u debbisect.log.good debbisect.log.bad
Since the command can easily become very long and quoting very involved, lets
instead use a script:
-
$ cat << END > script.sh
-
> #!/bin/sh
> set -exu
> mmdebstrap \
> --verbose \
> --aptopt='Acquire::Check-Valid-Until "false"' \
> --variant=apt \
> --include=pkga,pkgb,pkgc \
> --customize-hook='chroot "$1" dpkg -l' \
> --customize-hook='chroot "$1" do_something' \
> unstable \
> - \
> $DEBIAN_BISECT_MIRROR \
> >/dev/null
> END
-
$ chmod +x script.sh
$ ./debbisect --verbose --cache=./cache "two years ago" yesterday ./script.sh
$ diff -u debbisect.log.good debbisect.log.bad
$ rm -r ./cache
This example sets Acquire::Check-Valid-Until to not fail on snapshot timestamps
from "two years ago", uses the "apt" variant (only Essential:yes plus apt),
installs the packages required for the test using --include, runs "dpkg -l" so
that we can see which packages differed in the logs at the end and uses
--cache=cache so that the apt cache does not get discarded at the end and the
command can be re-run without downloading everything from snapshot.debian.org
again.
If you want to build a source package you can use the script shipped by
devscripts as /usr/share/doc/devscripts/examples/debbisect_buildsrc.sh and
either use it unmodified like this:
-
$ DEBIAN_BISECT_SRCPKG=mysrc ./debbisect "two years ago" yesterday > /usr/share/doc/devscripts/examples/debbisect_buildsrc.sh
or use the script as a starting point to do your own custom builds.
Once debbisect has finished bisecting and figured out the last good and the
first bad timestamp, there might be more than one package that differs in
version between these two timestamps. debbisect can figure out which package is
the culprit if you hand it control over installing dependencies for you via the
--depends option. With that option active, the script will not be responsible
to set up a chroot itself but is given the path to an existing chroot as the
first argument. Here is a real example that verifies the package responsible
for Debian bug #912935:
-
$ ./debbisect --depends=botch "2018-11-17" "2018-11-22" 'chroot "$1" botch-dose2html --packages=/dev/null --help'
-
[...]
test upgrading python3-minimal 3.6.7-1 -> 3.7.1-2...
-
upgrading python3-minimal triggered the problem
If you want to run above test under qemu, then you would run:
-
$ ./debbisect --depends=botch --qemu=defaults "2018-11-17" "2018-11-22" 'ssh -F "$1" qemu botch-dose2html --packages=/dev/null --help'
In the last two examples we omitted the --cache argument for brevity. But
please make use of it to reduce the load on snapshot.debian.org.
AUTHOR
Written by Johannes Schauer Marin Rodrigues <josch@debian.org>
Index
- NAME
-
- DESCRIPTION
-
- positional arguments:
-
- options:
-
- TIMESTAMPS
-
- ENVIRONMENT VARIABLES
-
- EXAMPLES
-
- AUTHOR
-
This document was created by
man2html,
using the manual pages.
Time: 13:23:42 GMT, April 27, 2024