NAME
apport-chroot - Create and use chroots for apport retracing
SYNOPSIS
apport-chroot [ options ] create release chrootpath
apport-chroot [ options ] retrace crashid
apport-chroot [ options ] retrace reportfile
apport-chroot [ options ] upgrade chroot
apport-chroot [ options ] upgrade all
apport-chroot [ options ] installdeb chroot debpath [ debpath ... ]
apport-chroot [ options ] login chroot
DESCRIPTION
Introduction
apport-chroot is a tool to create, update, and manage chroots for using
apport-retrace for several distributions and releases without needing
to touch the installed system at all. It uses fakeroot and fakechroot,
so that the entire reprocessing of apport reports which get submitted
to the crash database can happen on a system where you do not have any
root privileges or special packages installed.
Chroots can either be kept as a normal directory, or be stored as a
compressed tarball. In the latter case, the tarballs are temporarily
unpacked when using them. While unpacking takes a certain amount of
time, this is well compensated by not having to purge packages after
installing them for retracing, and being sure not to destroy the chroot
on failed upgrades, buggy maintainer scripts, etc. This also allows you
to use a chroot for several tasks in parallel.
Installation
If fakeroot or fakechroot themselves are not installed, you can just
put the libraries anywhere and set the environment variables
APPORT_LIBFAKEROOT and APPORT_LIBFAKECHROOT to the full path of
libfakeroot.so and libfakechroot.so. If the distribution packages are
installed, they will be found and used automatically.
Creating chroots
The create mode is mostly a wrapper around debootstrap which does the
grunt work of actually creating a basic chroot. apport-chroot then
does some additional modifications:
* Install some additional packages like apport-retrace and gpgv (as
well as extra packages specified with -p)
* Optionally set up additional apt sources (with -a)
* Adapt the apt sources.list if you use a file:// mirror
* Disable daemons with a policy-rc.d
* Clean up the apt package cache
The only two required arguments are the release name (passed to
debootstrap), and the target path (a directory, or the path to a
.tar.gz tarball). For the reasons stated above, you usually want to
supply --tar and some additional apt sources with -a.
Using chroots for retracing
In retrace mode, apport-chroot selects and prepares a chroot for the
crash to reprocess and calls apport-retrace in the chroot with the
crash file. Most of the options regarding retracing are passed to
apport-retrace, with making sure to properly handle file references by
symlinking them into the chroot.
In this mode you need to specify a "chroot map" which maps distribution
names and release versions to chroot paths. Please see the
documentation of -m/--chroot-map below for details.
If you want to enable duplicate checking, you need to specify the path
to the duplicate database. Please see --duplicate-db below for details.
Maintaining chroots
The most common maintenance operation is upgrade which takes a chroot
path as argument, or a DistroRelease: name if a chroot map is
specified. If all is specified as chroot name, all chroots in the
chroot map are upgraded.
To install a set of externally provided .deb packages into the chroot,
you can use the installdeb mode. This will temporarily copy the debs
into the chroot and install them with dpkg.
The login mode will provide a shell in the chroot which can be used for
general maintenance. If you use tarball chroots, you need to decide
whether you want to keep the changes after logging out (specify --save)
or throw them away (default).
In --save mode, you can still throw away the changes if you log out
with a nonzero exit code, i. e. by doing exit 1.
OPTIONS
--mirror=URL
Use an alternate archive mirror (passed to debootstrap).
This is only relevant in create mode. (Passed to debootstrap)
-p package, --extra-package=package
Install an additional package for the selected operation. May be
specified multiple times.
This is only relevant in create mode.
-a source, --apt-source=source
Add an extra apt source when creating chroots. May be specified
multiple times.
This is only relevant in create mode.
-t, --tar
Create a chroot tarball instead of a permanent directory.
This is only relevant in create mode, for other operations you
can specify a directory or a tarball.
--save When logging in to a chroot tarball, update the tarball
afterwards to save modifications if the shell exits with status
0.
This is only relevant in login mode if the chroot is a tarball.
-m MAP, --chroot-map=MAP
Path to chroot map. This file maps DistroRelease: values to
chroot paths (in the syntax of a Python dictionary). This needs
to be specified when refering to a chroot by distro release name
instead of a chroot path, or when using apport-chroot in retrace
mode and specifying a crash ID. In the latter case, the
DistroRelease: field is first read from the crash database, and
the appropriate chroot selected from that map. Example:
{
"Ubuntu 7.04": "chroots/feisty.tar.gz",
"Debian 3.1": "chroots/sarge.tar.gz",
}
-v, --verbose
Verbose operation. This option is also passed to apport-retrace
to report download/install progress when installing additional
packages.
--auth=authfile
If a bug number is given without any of the options -g, -s, or
-o, then the retraced stack traces are attached to the bug.
Since this needs authentication, an authentication file for the
crash database must be specified. This could e. g. be the
standard cookies.txt from Firefox' profile directory if the
crash database uses cookie based authentication. This option is
passed to apport-retrace (after copying the file into the
chroot).
--duplicate-db=dbfile
Specify path to the duplicate check database (in SQLite format).
The database will be created and initialized if it does not
exist. This option is passed to apport-retrace (after linking
the file into the chroot).
If not specified, apport-retrace will not check for duplicates.
--confirm-attach
Display retraced stack traces and ask for confirmation before
uploading them to the bug report. This option is ignored when
retracing report files. This option is just passed to apport-
retrace.
-h, --help
Print a short online help that documents all options.
AUTHOR
apport and the accompanying tools are developed by Martin Pitt
<martin.pitt@ubuntu.com>.