Provided by: apport-retrace_2.20.10-0ubuntu13_all bug

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