24.3. Configuring ABRT

A problem life cycle is driven by events in ABRT. For example:
  • Event #1 — a problem-data directory is created.
  • Event #2 — problem data is analyzed.
  • Event #3 — the problem is reported to Bugzilla.
Whenever a problem is detected, ABRT compares it with all existing problem data and determines whether that same problem has already been recorded. If it has, the existing problem data is updated, and the most recent (duplicate) problem is not recorded again. If the problem is not recognized by ABRT, a problem-data directory is created. A problem-data directory typically consists of files such as: analyzer, architecture, coredump, cmdline, executable, kernel, os_release, reason, time, and uid.
Other files, such as backtrace, can be created during the analysis of the problem, depending on which analyzer method is used and its configuration settings. Each of these files holds specific information about the system and the problem itself. For example, the kernel file records the version of a crashed kernel.
After the problem-data directory is created and problem data gathered, you can process the problem using either the ABRT GUI, or the abrt-cli utility for the command line. See Section 24.5, “Handling Detected Problems” for more information about the ABRT tools provided for working with recorded problems.

24.3.1. Configuring Events

ABRT events use plugins to carry out the actual reporting operations. Plugins are compact utilities that the events call to process the content of problem-data directories. Using plugins, ABRT is capable of reporting problems to various destinations, and almost every reporting destination requires some configuration. For instance, Bugzilla requires a user name, password, and a URL pointing to an instance of the Bugzilla service.
Some configuration details can have default values (such as a Bugzilla URL), but others cannot have sensible defaults (for example, a user name). ABRT looks for these settings in configuration files, such as report_Bugzilla.conf, in the /etc/libreport/events/ or $HOME/.cache/abrt/events/ directories for system-wide or user-specific settings respectively. The configuration files contain pairs of directives and values.
These files are the bare minimum necessary for running events and processing the problem-data directories. The gnome-abrt and abrt-cli tools read the configuration data from these files and pass it to the events they run.
Additional information about events (such as their description, names, types of parameters that can be passed to them as environment variables, and other properties) is stored in event_name.xml files in the /usr/share/libreport/events/ directory. These files are used by both gnome-abrt and abrt-cli to make the user interface more friendly. Do not edit these files unless you want to modify the standard installation. If you intend to do that, copy the file to be modified to the /etc/libreport/events/ directory and modify the new file. These files can contain the following information:
  • a user-friendly event name and description (Bugzilla, Report to Bugzilla bug tracker),
  • a list of items in a problem-data directory that are required for the event to succeed,
  • a default and mandatory selection of items to send or not send,
  • whether the GUI should prompt for data review,
  • what configuration options exist, their types (string, Boolean, and so on), default value, prompt string, and so on; this lets the GUI build appropriate configuration dialogs.
For example, the report_Logger event accepts an output filename as a parameter. Using the respective event_name.xml file, the ABRT GUI determines which parameters can be specified for a selected event and allows the user to set the values for these parameters. The values are saved by the ABRT GUI and reused on subsequent invocations of these events. Note that the ABRT GUI saves configuration options using the GNOME Keyring tool and by passing them to events, it overrides data from text configuration files.
To open the graphical Configuration window, choose Automatic Bug Reporting Tool → Preferences from within a running instance of the gnome-abrt application. This window shows a list of events that can be selected during the reporting process when using the GUI. When you select one of the configurable events, you can click the Configure button and modify the settings for that event.
Configuring ABRT Events

Figure 24.1. Configuring ABRT Events

Important

All files in the /etc/libreport/ directory hierarchy are world-readable and are meant to be used as global settings. Thus, it is not advisable to store user names, passwords, or any other sensitive data in them. The per-user settings (set in the GUI application and readable by the owner of $HOME only) are safely stored in GNOME Keyring, or they can be stored in a text configuration file in $HOME/.abrt/ for use with abrt-cli.
The following table shows a selection of the default analyzing, collecting, and reporting events provided by the standard installation of ABRT. The table lists each event's name, identifier, configuration file from the /etc/libreport/events.d/ directory, and a brief description. Note that while the configuration files use the event identifiers, the ABRT GUI refers to the individual events using their names. Note also that not all of the events can be set up using the GUI. For information on how to define a custom event, see Section 24.3.2, “Creating Custom Events”.

Table 24.1. Standard ABRT Events

NameIdentifier and Configuration FileDescription
uReport
report_uReport
 
Uploads a μReport to the FAF server.
Mailx
report_Mailx
mailx_event.conf
Sends the problem report via the Mailx utility to a specified email address.
Bugzilla
report_Bugzilla
bugzilla_event.conf
Reports the problem to the specified installation of the Bugzilla bug tracker.
Red Hat Customer Support
report_RHTSupport
rhtsupport_event.conf
Reports the problem to the Red Hat Technical Support system.
Analyze C or C++ Crash
analyze_CCpp
ccpp_event.conf
Sends the core dump to a remote retrace server for analysis or performs a local analysis if the remote one fails.
Report uploader
report_Uploader
uploader_event.conf
Uploads a tarball (.tar.gz) archive with problem data to the chosen destination using the FTP or the SCP protocol.
Analyze VM core
analyze_VMcore
vmcore_event.conf
Runs the GDB (the GNU debugger) on the problem data of a kernel oops and generates a backtrace of the kernel.
Local GNU Debugger
analyze_LocalGDB
ccpp_event.conf
Runs GDB (the GNU debugger) on the problem data of an application and generates a backtrace of the program.
Collect .xsession-errors
analyze_xsession_errors
ccpp_event.conf
Saves relevant lines from the ~/.xsession-errors file to the problem report.
Logger
report_Logger
print_event.conf
Creates a problem report and saves it to a specified local file.
Kerneloops.org
report_Kerneloops
koops_event.conf
Sends a kernel problem to the oops tracker at kerneloops.org.

24.3.2. Creating Custom Events

Each event is defined by one rule structure in a respective configuration file. The configuration files are typically stored in the /etc/libreport/events.d/ directory. These configuration files are loaded by the main configuration file, /etc/libreport/report_event.conf. There is no need to edit the default configuration files because abrt will run the scripts contained in /etc/libreport/events.d/. This file accepts shell metacharacters (for example, *, $, ?) and interprets relative paths relatively to its location.
Each rule starts with a line with a non-space leading character, and all subsequent lines starting with the space character or the tab character are considered a part of this rule. Each rule consists of two parts, a condition part and a program part. The condition part contains conditions in one of the following forms:
  • VAR=VAL
  • VAR!=VAL
  • VAL~=REGEX
where:
  • VAR is either the EVENT key word or a name of a problem-data directory element (such as executable, package, hostname, and so on),
  • VAL is either a name of an event or a problem-data element, and
  • REGEX is a regular expression.
The program part consists of program names and shell-interpretable code. If all conditions in the condition part are valid, the program part is run in the shell. The following is an event example: 
EVENT=post-create date > /tmp/dt
        echo $HOSTNAME `uname -r`
This event would overwrite the contents of the /tmp/dt file with the current date and time and print the host name of the machine and its kernel version on the standard output.
Here is an example of a more complex event, which is actually one of the predefined events. It saves relevant lines from the ~/.xsession-errors file to the problem report of any problem for which the abrt-ccpp service has been used, provided the crashed application had any X11 libraries loaded at the time of the crash: 
EVENT=analyze_xsession_errors analyzer=CCpp dso_list~=.*/libX11.*
        test -f ~/.xsession-errors || { echo "No ~/.xsession-errors"; exit 1; }
        test -r ~/.xsession-errors || { echo "Can't read ~/.xsession-errors"; exit 1; }
        executable=`cat executable` &&
        base_executable=${executable##*/} &&
        grep -F -e "$base_executable" ~/.xsession-errors | tail -999 >xsession_errors &&
        echo "Element 'xsession_errors' saved"
The set of possible events is not definitive. System administrators can add events according to their need in the /etc/libreport/events.d/ directory.
Currently, the following event names are provided with the standard ABRT and libreport installations:
post-create
This event is run by abrtd to process newly created problem-data directories. When the post-create event is run, abrtd checks whether the new problem data matches any of the already existing problem directories. If such a problem directory exists, it is updated and the new problem data is discarded. Note that if the script in any definition of the post-create event exits with a non-zero value, abrtd will terminate the process and will drop the problem data.
notify, notify-dup
The notify event is run following the completion of post-create. When the event is run, the user can be sure that the problem deserves their attention. The notify-dup is similar, except it is used for duplicate occurrences of the same problem.
analyze_name_suffix
where name_suffix is the replaceable part of the event name. This event is used to process collected data. For example, the analyze_LocalGDB event uses the GNU Debugger (GDB) utility to process the core dump of an application and produce a backtrace of the crash.
collect_name_suffix
…where name_suffix is the adjustable part of the event name. This event is used to collect additional information on problems.
report_name_suffix
…where name_suffix is the adjustable part of the event name. This event is used to report a problem.

24.3.3. Setting Up Automatic Reporting

ABRT can be configured to send initial anonymous reports, or μReports, of any detected issues or crashes automatically without any user interaction. When automatic reporting is turned on, the so called μReport, which is normally sent at the beginning of the crash-reporting process, is sent immediately after a crash is detected. This prevents duplicate support cases based on identical crashes. To enable the autoreporting feature, issue the following command as root: 
~]# abrt-auto-reporting enabled
The above command sets the AutoreportingEnabled directive in the /etc/abrt/abrt.conf configuration file to yes. This system-wide setting applies to all users of the system. Note that by enabling this option, automatic reporting will also be enabled in the graphical desktop environment. To only enable autoreporting in the ABRT GUI, switch the Automatically send uReport option to YES in the Problem Reporting Configuration window. To open this window, choose Automatic Bug Reporting Tool → ABRT Configuration from within a running instance of the gnome-abrt application. To launch the application, go to Applications → Sundry → Automatic Bug Reporting Tool.
Configuring ABRT Problem Reporting

Figure 24.2. Configuring ABRT Problem Reporting

Upon detection of a crash, by default, ABRT submits a μReport with basic information about the problem to Red Hat's ABRT server. The server determines whether the problem is known and either provides a short description of the problem along with a URL of the reported case if known, or invites the user to report it if not known.

Note

A μReport (microreport) is a JSON object representing a problem, such as a binary crash or a kernel oops. These reports are designed to be brief, machine readable, and completely anonymous, which is why they can be used for automated reporting. The μReports make it possible to keep track of bug occurrences, but they usually do not provide enough information for engineers to fix the bug. A full bug report is needed for a support case to be opened.
To change the default behavior of the autoreporting facility from sending a μReport, modify the value of the AutoreportingEvent directive in the /etc/abrt/abrt.conf configuration file to point to a different ABRT event. See Table 24.1, “Standard ABRT Events” for an overview of the standard events.