Provided by: apport-retrace_2.20.1-0ubuntu2.30_all 
NAME
apport-retrace - regenerate a crash report's stack trace
SYNOPSIS
apport-retrace [ OPTIONS ] report
DESCRIPTION
apport-retrace regenerates the stack traces (both the simple and the threaded one) in an
apport crash report from the included core dump. For this it figures out the set of
necessary packages and their accompanying debug symbol packages, so that the regenerated
stack trace will be fully symbolic and thus become much more useful for developers to fix
the problem.
apport-retrace has two modes: By default it will just regenerate traces based on the
packages which are currently installed in the system, i. e. it assumes that all necessary
debug symbols for the report are installed. When specifying the -S option, it creates a
temporary "sandbox" and downloads and installs all necessary packages and debug symbols
there. It will not do any changes to your system. This does not require root privileges,
as it does not actually use the chroot() system call, but just supplies some "virtual
root" options to gdb.
If you regularly use apport-retrace in sandbox mode, it is highly recommended to use a
permanent cache directory (the --cache option).
report is either the path to a .crash file, or a bug number. In the latter case, the
information is downloaded from the bug report, and either one of the options -g, -s, or -o
have to be used to process the report locally, or --auth needs to be specified to attach
the resulting stack traces back to the bug report.
OPTIONS
-c, --remove-core
Remove the core dump from the report after stack trace regeneration. By default it
is retained.
-g, --gdb
Start an interactive gdb session with the report's core dump.
-s, --stdout
Write the new stack traces to stdout instead of putting them back into the report.
-o FILE, --output=FILE
Write modified report to given file instead of changing the original report.
-R, --rebuild-package-info
(Re-)generate Packages: and Dependenencies: fields before retracing. This is
particularly useful if you want to retrace a .crash report before it was completed
by running it through the UI data collection phase. However, this only works when
you run this on the very same system where the crash happened.
-S CONFIG_DIR, --sandbox=CONFIG_DIR
Build a temporary sandbox and download/install the necessary packages and debug
symbols in there; without this option it assumes that the necessary packages and
debug symbols are already installed in the system.
The argument points to the packaging system configuration directory, which needs to
have a subdirectory for the DistroRelease field in the report (e. g. "config/Ubuntu
11.04/"), which contains the package system configuration.
When using the apt/dpkg backend (Debian/Ubuntu based distributions), the per-
release directory must contain an apt sources.list file with package sources for
this release, plus the corresponding debug symbol package repository.
Sandboxing is not implemented for other (RPM based) backends right now.
If CONFIG_DIR is "system", it will use the system configuration files, but will
then only be able to retrace crashes that happened on the currently running
release.
-v, --verbose
Report download/install progress when installing packages in sandbox mode.
-p, --extra-package
Install an additional package for retracing into the sandbox. May be specified
multiple times.
-C DIR, --cache=DIR
Permanent cache directory for downloaded package indexes and packages for sandbox
mode. If not specified all indexes and packages will have to be re-downloaded at
each run of apport-retrace. If you use sandbox mode regularly, using a permanent
cache directory is highly recommended.
--sandbox-dir=DIR
Permanent directory for the sandbox of extracted packages. If not specified all
cached packages will have to be re-extracted at each run of apport-retrace. If you
use sandbox mode regularly, using a permanent cache directory is highly
recommended.
-h, --help
Print a short help that documents all options.
--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.
--confirm
Display retraced stack traces and ask for confirmation before uploading them to the
bug report. This option is ignored when retracing report files.
--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. If not specified, apport-retrace
will not check for duplicates.
EXAMPLES
Reprocess recent local gedit crash report after the debug symbol packages have been
installed into the system, and show reprocessed stack traces on stdout:
apport-retrace --stdout /var/crash/_usr_bin_gedit.1000.crash
Build a sandbox with all necessary packages and debug symbols, and start a gdb session on
the report's core file:
apport-retrace --gdb --sandbox system --cache ~/.cache/apport-retrace
/var/crash/_usr_bin_gedit.1000.crash
Download crash report bug #12345, run in sandbox mode with local configuration files, and
reupload updated traces to the bug (as neither -g or -s is specified):
apport-retrace --auth ~/.cache/apport/launchpad.credentials -S ~/retrace-conf/ -C
~/.cache/apport-retrace 12345
AUTHOR
apport and the accompanying tools are developed by Martin Pitt <martin.pitt@ubuntu.com>.