| DEBBISECT(1) | User Commands | DEBBISECT(1) |
debbisect - bisect snapshot.debian.org
usage: debbisect [-h] [-d] [-v] [--cache CACHE] [--nocache] [--port PORT]
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 proxy 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:
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.
Valid good and bad timestamp formats are either:
Without specifying the timezone explicitly, the local offset is used.
Examples (corresponding to the items in above list, respectively):
The earliest timestamp that works with debbisect should be 2006-08-10.
The following environment variables are available to the test script:
DEBIAN_BISECT_MIRROR Contains the snapshot.d.o mirror address including the
DEBIAN_BISECT_EPOCH Contains an integer representing the unix epoch of the
DEBIAN_BISECT_TIMESTAMP Contains a timestamp in the format used by
DEBIAN_BISECT_* All environment variables starting with DEBIAN_BISECT_
http_proxy The address of the apt http caching proxy. Unset the
Just run "do_something" which runs the test and returns a non-zero exit on failure.
Since the command can easily become very long and quoting very involved, lets instead use a script:
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:
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:
If you want to run above test under qemu, then you would run:
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.
Written by Johannes Schauer Marin Rodrigues <josch@debian.org>
| August 2025 | debbisect 2.25.15+deb13u1 |