File an Apport Bug Report from a Linux Terminal

You will finish with a repeatable way to inspect Apport's installed interface, create a report for a package or running process, save it for review, and understand when a command will upload data. The examples use apport-cli from Apport package version 2.28.3-0ubuntu0.1 on the machine used for this guide.

Allow about fifteen minutes. You need a shell and a package or process that you can identify. A report can contain system details, package versions, logs and data about a process. Read the report before sending it, and do not paste real private paths or customer data into a public bug.

1. Check the installed command

Start with read-only checks. They need no elevated privileges and confirm which executable and package you are using:

$ command -v apport-cli
/usr/bin/apport-cli
$ dpkg-query -W -f='${Package} ${Version}\n' apport
apport 2.28.3-0ubuntu0.1
$ apport-cli --version
2.28.3

Read the local manual as well as the command's help. On this installation, the help calls the update operation --update-bug, while the installed manual documents --update-report. The short option -u is the least ambiguous spelling when you need that operation:

$ apport-cli --help
usage: apport-cli [options] [symptom|pid|package|program path|.apport/.crash file]
$ man apport-cli

Checkpoint: if the version or option names differ on another host, follow that host's help and manual. Do not copy a newer option into an older system without checking it.

2. Decide whether you are reporting a crash or a bug

Apport handles pending crash reports, non-crash package problems, running processes and saved .crash or .apport files. With no options, it processes pending reports from /var/crash/ one by one:

$ apport-cli

This is an interactive workflow. It may offer to send existing reports, so do not run it blindly on a production host. If you already know the report file, naming it gives you a narrower target:

$ apport-cli /path/to/problem.crash

Only use a path ending in .crash or .apport. Treat the file as sensitive evidence. Copying it to another machine may disclose usernames, paths, environment details or excerpts from application data.

3. Save a package report instead of sending it

For a problem that is not a crash, use file-bug mode and name the affected package. The save option collects the report into a local file rather than reporting it immediately:

$ apport-cli --file-bug --package PACKAGE_NAME --save /tmp/PACKAGE_NAME.apport

Replace PACKAGE_NAME with the Debian package that owns the faulty component, such as a package installed on your machine. Apport will ask interactive questions and collect operating-system and package-version context. The file is written under /tmp in this example, so protect it from other users according to your host's policy and remove it after review.

Checkpoint: confirm that the collection created a non-empty file before you do anything with it:

$ test -s /tmp/PACKAGE_NAME.apport && echo 'report saved'
report saved
$ ls -lh /tmp/PACKAGE_NAME.apport

If the package name is uncertain, do not guess. The manual also supports symptom scripts, which ask questions and select a package. List them by starting file-bug mode without a package, or name one explicitly with --symptom:

$ apport-cli --file-bug
$ apport-cli --file-bug --symptom SYMPTOM_NAME --save /tmp/symptom-report.apport

The available symptoms come from /usr/share/apport/symptoms/*.py and vary by installation. If none are available, the first command stops with an error.

4. Include a running process only when it helps

A process report can add useful context when a program is currently misbehaving. Find its PID without changing anything:

$ ps -ux
$ apport-cli --file-bug --package PACKAGE_NAME --pid PID --save /tmp/process-report.apport

Replace PID with the numeric process ID. The process may be inspected while the report is collected, and the result can contain more information than a package-only report. Obtain the owner's approval before collecting from another user's process, and avoid using this route for secrets or sensitive workloads unless your incident process permits it.

Do not use a PID merely because the program is available. For a crashed process, use the matching pending crash report instead. For a hung process, the installed command also accepts --hanging with file-bug mode; use it only when the program is genuinely stuck, not as a generic extra flag.

5. Review the saved report before uploading

Inspect the file as text where practical, but remember that report fields can be long:

$ less /tmp/PACKAGE_NAME.apport
$ file /tmp/PACKAGE_NAME.apport

Look for private usernames, home-directory paths, command-line arguments, hostnames, log excerpts, tokens and customer identifiers. Do not edit a report with a blind search-and-replace: changing its structure can make it unusable. If it contains data that cannot be shared, stop and use your organisation's redaction or bug-report process.

When the contents are suitable for the project's bug tracker and the machine has the required network access, report the saved file explicitly:

$ apport-cli --crash-file /tmp/PACKAGE_NAME.apport

This is the point at which an upload or interactive submission may occur. Read every prompt. A successful command does not mean that the report was safe to disclose; it only means that Apport completed its workflow.

6. Update an existing report carefully

Apport can collect fresh information for an existing report number. This changes the report workflow and may contact the bug tracker, so confirm the number before starting:

$ apport-cli -u REPORT_NUMBER

The affected package is taken from the existing report by default. If the report was assigned to the wrong package, the manual allows an explicit package:

$ apport-cli -u REPORT_NUMBER --package PACKAGE_NAME

Use a real report number in place of REPORT_NUMBER. Do not treat -u as an undo operation: it updates information; it does not retract an uploaded report. If you started the wrong interactive action, answer its cancellation choice and check the tracker separately.

7. Handle obsolete-package checks and permissions

Apport normally refuses to create a report when the package or one of its dependencies is obsolete. The APPORT_IGNORE_OBSOLETE_PACKAGES environment variable bypasses that check:

$ APPORT_IGNORE_OBSOLETE_PACKAGES=1 apport-cli --file-bug --package PACKAGE_NAME --save /tmp/obsolete-package.apport

Use this only after checking the package state yourself. It is not a repair command and can produce a report against a problem already fixed by an update. Do not place the setting permanently in your shell startup file unless you understand the reporting policy it changes.

Most read-only checks and report collection run as the invoking user. Use elevated privileges only when the command explicitly reports that it cannot read a required file or pending report. Do not use sudo to bypass an unknown package, an unsafe disclosure decision or a missing symptom script.

8. Clean up a temporary saved report

After the report has been reviewed and either submitted or retained according to your incident process, remove the temporary copy if it is no longer needed:

$ rm -- /tmp/PACKAGE_NAME.apport

This deletion is irreversible. Check the exact path first, and do not run it if the file is evidence that must be retained. A saved report is not a backup of the original application state.