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>.