~ubuntu-core-dev/ubuntu/groovy/apport/ubuntu

.TH apport\-retrace 1 "September 09, 2006" "Martin Pitt"

.SH NAME

apport\-retrace \- regenerate a crash report's stack trace

.SH SYNOPSIS

.B apport\-retrace
[
.I OPTIONS
]
.I report

.SH DESCRIPTION

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

.B 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
.B \-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
.B chroot()
system call, but just supplies some "virtual root" options to
.B gdb\fR.

If you regularly use
.B apport\-retrace
in sandbox mode, it is highly recommended to use a permanent cache directory
(the \fB\-\-cache\fR option).

.I 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
.B \-g\fR,
.B \-s\fR, or
.B \-o\fR
have to be used to process the report locally, or 
.B \-\-auth
needs to be specified to attach the resulting stack traces back to the
bug report.

.SH OPTIONS

.TP
.B \-c, \-\-remove\-core
Remove the core dump from the report after stack trace regeneration.
By default it is retained.

.TP
.B \-g, \-\-gdb
Start an interactive gdb session with the report's core dump.

.TP
.B \-s, \-\-stdout
Write the new stack traces to stdout instead of putting them back into
the report.

.TP
.B \-o \fIFILE\fR, \fB\-\-output=\fIFILE
Write modified report to given file instead of changing the original
report.

.TP
.B \-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.

.TP
.B \-S \fICONFIG_DIR\fR, \fB\-\-sandbox=\fICONFIG_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
.B 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
.B 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
.I 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.

.TP
.B \-v, \-\-verbose
Report download/install progress when installing packages in sandbox mode.

.TP
.B \-p, \-\-extra\-package
Install an additional package for retracing into the sandbox. May be specified
multiple times.

.TP
.B \-C \fIDIR\fR, \fB\-\-cache=\fIDIR
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
.B apport\-retrace\fR.
If you use sandbox mode regularly, using a permanent cache directory is highly
recommended.

.TP
.B \-\-sandbox\-dir=\fIDIR
Permanent directory for the sandbox of extracted packages. If not specified all
cached packages will have to be re-extracted at each run of
.B apport\-retrace\fR.
If you use sandbox mode regularly, using a permanent cache directory is highly
recommended.

.TP
.B \-h, \-\-help
Print a short help that documents all options.

.TP
.B \-\-auth=\fIauthfile
If a bug number is given without any of the options
.B \-g\fR,
.B \-s\fR, or
.B \-o\fR,
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
.B cookies.txt
from Firefox' profile directory if the crash database uses
cookie based authentication.

.TP
.B \-\-confirm
Display retraced stack traces and ask for confirmation before
uploading them to the bug report. This option is ignored when
retracing report files.

.TP
.B \-\-duplicate\-db=\fIdbfile
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,
.B apport\-retrace
will not check for duplicates.

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

.RS 4
apport\-retrace \-\-stdout /var/crash/_usr_bin_gedit.1000.crash
.RE

Build a sandbox with all necessary packages and debug symbols, and start a gdb
session on the report's core file:

.RS 4
apport\-retrace \-\-gdb \-\-sandbox system \-\-cache ~/.cache/apport\-retrace /var/crash/_usr_bin_gedit.1000.crash
.RE

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):

.RS 4
apport\-retrace \-\-auth ~/.cache/apport/launchpad.credentials \-S ~/retrace-conf/ \-C ~/.cache/apport\-retrace 12345
.RE

.SH AUTHOR
.B apport
and the accompanying tools are developed by Martin Pitt
<martin.pitt@ubuntu.com>.