Configuration

Configuration files

Upon installation, ABRT and libreport place their respective configuration files into the several directories on a system:

/etc/libreport/
contains the report_event.conf main configuration file. More information about this configuration file can be found in Event configuration.
/etc/libreport/events/
holds files specifying the default setting of predefined events.
/etc/libreport/events.d/
keeps configuration files defining events.
/etc/libreport/plugins/
contains configuration files of programs that take part in events.
/etc/abrt/
holds ABRT specific configuration files used to modify the behavior of ABRT’s services and programs. More information about certain specific configuration files can be found in ABRT Specific Configuration.
/etc/abrt/plugins/
keeps configuration files used to override the default setting of ABRT’s services and programs. For more information on some specific configuration files refer to ABRT Specific Configuration.

The configuration files expect Key-Value pairs separated by an equal sign. Quoting of the values is not supported.

ABRT Specific Configuration

Standard ABRT installation currently provides the following ABRT specific configuration files:

/etc/abrt/abrt.conf
allows you to modify the behavior of the abrtd service.
/etc/abrt/abrt-action-save-package-data.conf
allows you to modify the behavior of the abrt-action-save-package-data program.
/etc/abrt/plugins/CCpp.conf
allows you to modify the behavior of ABRT’s core catching hook.

The following configuration directives are supported in the /etc/abrt/abrt.conf file:

  • WatchCrashdumpArchiveDir = /var/spool/abrt-upload

Enable this directive if you want abrtd to auto-unpack crashdump tarball archives (.tar.gz) which are located in the specified directory. In the example above, it is the /var/spool/abrt-upload/ directory. Whichever directory you specify in this directive, you must ensure that it exists and it is writable for abrtd. The ABRT daemon will not create it automatically. If you change the default value of this option, be aware that in order to ensure proper functionality of ABRT, this directory must not be the same as the directory specified for the DumpLocation option.

Caution

Do not modify this option when using SELinux

Changing the location for crashdump archives will cause SELinux denials unless you reflect the change in respective SELinux rules first. See the abrt_selinux(8) manual page for more information on running ABRT in SELinux.

Remember that if you enable this option when using SELinux, you need to execute the following command in order to set the appropriate SELinux boolean allowing ABRT to write into the public_content_rw_t domain:

setsebool -P abrt_anon_write 1
  • MaxCrashReportsSize = size_in_mebibytes

This option sets the amount of storage space, in mebibytes, used by ABRT to store all problem information from all users. The default setting is 5000 MiB. Once the quota specified here has been met, ABRT will continue catching problems, and in order to make room for the new crash dumps, it will delete the oldest and largest ones.

  • DumpLocation = /var/spool/abrt

This directive specifies the location where problem data directories are created and in which problem core dumps and all other problem data are stored. The default location is set to the /var/spool/abrt directory. Whichever directory you specify in this directive, you must ensure that it exists and it is writable for abrtd. If you change the default value of this option, be aware that in order to ensure proper functionality of ABRT, this directory must not be the same as the directory specified for the WatchCrashdumpArchiveDir option.

Caution

Do not modify this option when using SELinux

Changing the dump location will cause SELinux denials unless you reflect the change in respective SELinux rules first. See the abrt_selinux(8) manual page for more information on running ABRT in SELinux.

Remember that if you enable this option when using SELinux, you need to execute the following command in order to set the appropriate SELinux boolean allowing ABRT to write into the public_content_rw_t domain:

setsebool -P abrt_anon_write 1

The following configuration directives are supported in the /etc/abrt/abrt-action-save-package-data.conf file:

  • OpenGPGCheck = yes/no

Setting the OpenGPGCheck directive to yes (the default setting) tells ABRT to only analyze and handle crashes in applications provided by packages which are signed by the GPG keys whose locations are listed in the /etc/abrt/gpg_keys file. Setting OpenGPGCheck to no tells ABRT to catch crashes in all programs.

  • BlackList = nspluginwrapper, valgrind, strace, [more_packages ]

Crashes in packages and binaries listed after the BlackList directive will not be handled by ABRT. If you want ABRT to ignore other packages and binaries, list them here separated by commas.

  • ProcessUnpackaged = yes/no

This directive tells ABRT whether to process crashes in executables that do not belong to any package. The default setting is no.

  • BlackListedPaths = /usr/share/doc/*, */example*

Crashes in executables in these paths will be ignored by ABRT.

The following configuration directives are supported in the /etc/abrt/plugins/CCpp.conf file:

  • MakeCompatCore = yes/no

This directive specifies whether ABRT’s core catching hook should create a core file, as it could be done if ABRT would not be installed. The core file is typically created in the current directory of the crashed program but only if the ulimit -c setting allows it. The directive is set to yes by default.

  • SaveBinaryImage = yes/no

This directive specifies whether ABRT’s core catching hook should save a binary image to a core dump. It is useful when debugging crashes which occurred in binaries that were deleted. The default setting is no.

Configuring ABRT to Detect a Kernel Panic

ABRT can detect a kernel panic using the abrt-vmcore service, which is provided by the abrt-addon-vmcore package. The service starts automatically on system boot and searches for a core dump file in the /var/crash/ directory. If a core dump file is found, abrt-vmcore creates the problem data directory in the /var/spool/abrt/ directory and copies the core dump file to the newly created problem data directory. After the /var/crash/ directory is searched through, the service is stopped until the next system boot.

To configure ABRT to detect a kernel panic, perform the following steps:

  1. Ensure that the kdump service is enabled on the system. Especially, the amount of memory that is reserved for the kdump kernel has to be set correctly. You can set it by using the system-config-kdump graphical tool, or by specifying the crashkernel parameter in the list of kernel options in the /etc/grub2.conf configuration file.

  2. Install and enable the abrt-addon-vmcore package using yum:

    yum install abrt-addon-vmcore
    systemctl enable abrt-vmcore
    

    This installs the abrt-vmcore service with respective support and configuration files.

  3. Reboot the system for the changes to take effect.

Unless ABRT is configured differently, problem data for any detected kernel panic is now stored in the /var/spool/abrt/ directory and can be further processed by ABRT just as any other detected kernel oops.

Desktop Session Autoreporting

Enabled autoreporting behavior

With the desktop session autoreporting enabled, ABRT automatically uploads μReport for user problems immediately upon their detection. If the abrt server (faf) knows the reported problem, the server provides additional information about the problem and ABRT informs the user that the detected problem is known via a notification bubble. The notification bubble offers showing the problem’s web page, opening the problem in the ABRT GUI or simply ignoring the problem. If the problem is unknown, ABRT shows a notification bubble and the user can either start reporting process as usual or ignore the problem.

Disabled autoreporting behavior

With the autoreporting disabled, ABRT uploads an μReport for the detected problem after click on “Report” button in the notification bubble. If the detected problem is not known to abrt server, ABRT proceeds with reporting wizard.

Event though ABRT notifies about problems of other users, it never uploads uReports for these problems automatically. The other user’s problems are always processed in the way of processing problems with the autoreporting disabled, which is described in the 2nd paragraph.

In case of unavailable network, ABRT will postpone notification of the detected problems until the network becomes available again. The list of postponed problems will be held only for a single user desktop session. The postponed problems may not be notified at all, if the network won’t become available during the desktop session’s lifetime.

Uploading uReports requires a writeable problem directory and in order to make the reporting more automatic and less confusing, ABRT might move the problem directory from the system dump location (usually /var/spool/abrt/ directory) to $HOME/.cache/abrt/spool/ directory without asking the user for a permission to do so. However, ABRT moves the directories only if the user has no rights for writing to the system dump location.

Enabling desktop session autoreporting

The desktop autoreporting can be enabled in various ways. The easiest way is to answer Yes in a dialogue asking for enabling automatically submitted crash reports which appears after clicking on “Report” button in the notification bubble. The second way is to open the Automatic Bug Reporting Tool application, open the application menu and click on the following option:

ABRT Configuration

and turn on option:

Automatically send uReport

The last but the most inconvenient way is to manually edit file:

$HOME/.config/abrt/settings/abrt-applet.conf

and add the following line:

AutoreportingEnabled = yes

System Autoreporting

ABRT can be configured to submit an μReport for each of the detected problems to the abrt server (faf) immediately upon their detection. The server provides the following information about the submitted problem:

  • URLs to existing bug reports if any (Bugzilla bugs)
  • short description text

System Autoreporting can be enabled by issuing the following command:

abrt-auto-reporting enabled

or via Augeas:

augtool set /files/etc/abrt/abrt.conf/AutoreportingEnabled yes

or by adding the following line to the /etc/abrt/abrt.conf configuration file:

AutoreportingEnabled yes

When System Autoreporting is enabled, Desktop Session Autoreporting is enabled too.

Shortened Reporting

Enables shortened GUI reporting where the reporting is interrupted after AutoreportingEvent is done. It means that the reporting is done when user clicks “Report” button on the notification bubble. Upon that, ABRT uploads an uReport describing handled problem, shows a notification bubble stating that the problem has been reported and finishes.

Shortened Reporting has no effect on the reporting process started from the GUI, because we wanted to allow advanced users to easily submit full bug report into Bugzilla. We believe that all users who care about detected crashes and open Automatic Bug Reporting Tool application to see them are advanced users.

Default value: Yes but only if application is running in GNOME desktop

To turn Shortened Reporting on open:

Automatic Bug Reporting Tool

go to the application menu and click:

ABRT Configuration

and turn on option:

Shortened Reporting

Or manually edit file:

$HOME/.config/abrt/settings/abrt-applet.conf

and add there the following line:

ShortenedReporting = yes

Automatic sensitive data filtering

ABRT keeps the global list of sensitive words in /etc/libreport/forbidden_words.conf so in order to change this list for all users, system administrator has to edit this file. There is also per-user list in $HOME/.config/abrt/settings/forbidden_words.conf (doesn’t exist by default, so user has to create it). The format of the file is one word per line. Wildcards are NOT supported.

The forbidden words are sometimes a part of other words and these are usually not deemed as sensitive information. Offering such false positive sensitive words for review by user makes the process of removing sensitive data from reports hard and the real sensitive data may be missed. Therefore, ABRT has another list of words that are never considered as sensitive information. The list contains common words consisting from the sensitive words. The global list of ignored words is kept in file:

/etc/libreport/ignored_words.conf

And the per-user list:

$HOME/.config/abrt/settings/ignored_words.conf

Event configuration

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.

The /etc/libreport/report_event.conf file consists of include directives and rules. Rules are typically stored in other configuration files in the /etc/libreport/events.d/ directory.

If you would like to modify this file, please note that it respects shell metacharacters (*, $, ?, etc.) and interprets relative paths relatively to its location.

Each rule starts with a line with a non-space leading character, 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, … See Elements collected by ABRT for more.
  • 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 hostname of the machine and its kernel version on the standard output.

Here is an example of a yet more complex event which is actually one of the predefined events. It saves relevant lines from the ~/.xsession-errors file to the problem report for any problem for which the abrt-ccpp services has been used to process that problem, and the crashed application has loaded any X11 libraries at the time of 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 hard-set. System administrators can add events according to their need. Currently, the following event names are provided with standard ABRT and libreport installation:

post-create
This event is run automatically by abrtd on newly created problem data directories. When the post-create event is run, abrtd checks whether the UUID identifier of the new problem data matches the UUID of any already existing problem directories. If such a problem directory exists, the new problem data is deleted. See Deduplication for more details on duplicate handling.
analyze_name_suffix
where name_suffix is the adjustable part of the event name. This event is used to process collected data. For example, the analyze_LocalGDB runs the GNU Debugger (GDB) utility on a core dump of an application and produces a backtrace of a crash.
collect_name_suffix
where name_suffix is the adjustable part of the event name. This event is used to collect additional information on a problem.
report_name_suffix
where name_suffix is the adjustable part of the event name. This event is used to report a problem.

Additional information about events (such as their description, names and types of parameters which can be passed to them as environment variables, and other properties) is stored in the /etc/libreport/events/event_name.xml files. These files are used by both GUI and CLI to make the user interface more friendly. Do not edit these files unless you want to modify the standard installation.

Standard ABRT Installation Supported Events

Standard ABRT installation currently provides a number of default analyzing, collecting and reporting events. Some of these events are configurable using the gnome-abrt GUI application. The following is a list of default analyzing, collecting and reporting events provided by the standard installation of ABRT:

analyze_VMcore — Analyze VM core
Runs GDB (the GNU debugger) on problem data of an application and generates a backtrace of the kernel. It is defined in the /etc/libreport/events.d/vmcore_event.conf configuration file.
analyze_LocalGDB — Local GNU Debugger
Runs GDB (the GNU debugger) on problem data of an application and generates a backtrace of a crash. It is defined in the /etc/libreport/events.d/ccpp_event.conf configuration file.
analyze_RetraceServer — Generate backtrace remotely
Uploads core dump to retrace server for remote backtrace generation. It is defined in the /etc/libreport/events.d/ccpp_retrace_event.conf configuration file.
analyze_xsession_errors — Collect .xsession-errors
Saves relevant lines from the ~/.xsession-errors file to the problem report. It is defined in the /etc/libreport/events.d/ccpp_event.conf configuration file.
report_Logger — Logger
Creates a problem report and saves it to a specified local file. It is defined in the /etc/libreport/events.d/print_event.conf configuration file.
report_Mailx — Mailx
Sends a problem report via the mailx utility to a specified email address.i It is defined in the /etc/libreport/events.d/mailx_event.conf configuration file.
report_Uploader — Report uploader
Uploads a tarball (.tar.gz) archive with problem data to the chosen destination using the FTP or the SCP protocol. It is defined in the /etc/libreport/events.d/uploader_event.conf configuration file.
report_uReportμReport uploader
Uploads μReport to faf server.
report_EmergencyAnalysis — Upload problem directory to faf
Uploads a tarball to faf server for further analysis. Used in case of reporting failure when standard reporting methods fail. It is defined in the /etc/libreport/events.d/emergencyanalysis_event.conf configuration file.

Workflow configuration

report-gtk and report-cli are tools that report application crashes and other problems caught by abrtd daemon, or created by other programs using libreport. To do so, they invoke so called EVENTs. There are two ways to specify an EVENT to be performed. Either it can be specified as a command line argument (option -e EVENT) to report-gtk/report-cli, or it can be defined in a workflow file located in /usr/share/libreport/workflows/. Which of these workflow files will be used is defined in workflow configuration files in /etc/libreport/workflows.d/.

Every EVENT which is used in a workflow must have its corresponding XML description file in /usr/share/libreport/events/. The format of these files is described in the report_event.conf(5) man page.

Workflow file

Each XML file in /usr/share/libreport/workflows/ must conform to the following DTD:

<!ELEMENT workflow    (name+,description+,priority?,events*)>
<!ELEMENT name        (#PCDATA)>
<!ATTLIST name         xml:lang CDATA #IMPLIED>
<!ELEMENT description (#PCDATA)>
<!ATTLIST description  xml:lang CDATA #IMPLIED>
<!ELEMENT priority =  (#PCDATA)>
<!ELEMENT events =    (event)+>
<!ELEMENT event =     (#PCDATA)>
name
User-facing name of the workflow.
description
User-facing description of the workflow.
priority
Priority of the workflow. Higher number means a more visible place in the user interface. If none is provided, 0 is used. The value is a signed integer.
events
List of events executed in the workflow.
event
Name of the event to be executed. You may also use a wildcard (*) at the end of the name to select multiple events with a common prefix. If an event is not applicable to the problem data or if it is not defined, the process continues with next event sibling.

Workflow configuration file

The configuration file contains rules governing which of the workflows shall be executed under the given conditions. Each rule starts with a line with a non-space leading character. Each rule consists of two parts, the name of a workflow and an optional condition in following format:

EVENT=<WORKFLOW_NAME> [CONDITION]

The latter part consists of a space-separated list of conditions in one of the following forms:

VAR=VAL,

VAR!=VAL, or

VAL~=REGEX

where:

  • VAR is a problem data directory element (such as executable, package, hostname, etc. – see Elements collected by ABRT for more),
  • VAL is a problem data element, and
  • REGEX is a regular expression.

Loading procedure

report-gtk or report-cli looks into the /etc/libreport/workflows.d/ directory and goes trough all rules in each of the configuration files, checking if the specified conditions of each rule are satisfied.

If there is only one workflow whose conditions are satisfied, its specification is loaded from /usr/share/libreport/workflows/<WORKFLOW_NAME>.xml and each of its events is executed. If multiple workflows match the conditions, the user is given a choice wich of them should be executed.

Example workflow

To illustrate the process, we provide an example of creating a workflow for mailx, the POSIX mail utility. The first step is to create a workflow configuration file in /etc/libreport/workflows.d/ with the following content:

EVENT=workflow_mailx analyzer=CCpp

This instructs the reporter to look for a workflow_mailx.xml file in /usr/share/libreport/workflow/ whenever the analyzer is CCpp (the crash analyzer for C and C++).

In the second step, we create the required workflow file, workflow_mailx.xml, with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<workflow>
    <name>Send the problem data via mailx</name>
    <description>Analyze the problem locally and send information via mailx</description>
    <priority>-99</priority>

    <events>
        <event>report_Mailx</event>
    </events>
</workflow>

It instructs the reporter (report-gtk or report-cli) to run the event report_Mailx as the only step of this workflow.

The third step is to create the EVENT configuration file report_Mailx.xml which corresponds to the report_Mailx EVENT from the workflow_mailx.xml configuration file described above. The content of this file may be as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<event>
    <name>Mailx</name>
    <description>Send via email</description>

    <requires-items></requires-items>
    <exclude-items-by-default>count,event_log,reported_to,coredump,vmcore</exclude-items-by-default>
    <exclude-items-always></exclude-items-always>
    <exclude-binary-items>no</exclude-binary-items>
    <include-items-by-default></include-items-by-default>
    <minimal-rating>0</minimal-rating>
    <gui-review-elements>yes</gui-review-elements>

    <options>
        <option type="text" name="Mailx_Subject">
            <label>Subject</label>
            <allow-empty>no</allow-empty>
            <description>Message subject</description>
            <default-value>[abrt] detected a crash</default-value>
        </option>
        <option type="text" name="Mailx_EmailFrom">
            <label>Sender</label>
            <allow-empty>no</allow-empty>
            <description>Sender's email</description>
        </option>
        <option type="text" name="Mailx_EmailTo">
            <label>Recipient</label>
            <allow-empty>no</allow-empty>
            <description>Recipient's email</description>
        </option>
        <option type="bool" name="Mailx_SendBinaryData">
            <label>Send Binary Data</label>
            <description>Send binary files like coredump</description>
            <default-value>no</default-value>
        </option>
    </options>
</event>

Adjusting plugin configuration

ABRT reports problems to various destinations. Almost every reporting destination require some configuration. For instance, Bugzilla requires login and password and URL to an instance of the Bugzilla service. Some configuration details can have default values (e.g. Bugzilla’s URL) but others don’t have sensible defaults (e.g. login).

ABRT lets user provide configuration through text configuration files, such as /etc/libreport/events/report_Bugzilla.conf. All text configuration files consist of key/value pairs.

The event text configuration can be stored in one of these files:

  • /etc/libreport/events/somename.conf - for system scope configuration
  • $XDG_CACHE_HOME/abrt/events/somename.conf - for user scope configuration [XDG]

These files are the bare minimum necessary for running events on the problem directories. ABRT GUI and CLI tools will read configuration data from these files and pass it down to events they run.

However, in order to make GUI interface more user-friendly, additional information can be supplied in XML files in the same directory, such as report_Bugzilla.xml. These files can contain the following information:

  • user-friendly event name and description (Bugzilla, Report to Bugzilla bug tracker).
  • the list of items in problem directory which are required for event to succeed.
  • default and mandatory selection of items to send or not send.
  • whether GUI should prompt for data review.
  • what configuration options exist, their type (string, boolean, etc), default value, prompt string, etc. This lets GUI to build the appropriate configuration dialogs.

ABRT’s GUI saves configuration options in gnome-keyring or ksecrets and passes them down to events, overriding data from text configuration files.

You can obtain a set of keys for a particular event by executing of the following command:

xmllint --xpath "/event/options/option/@name" $EVENT_XML_FILE | sed 's/name="\([^ ]*\)"/\1\n/g'

The mapping between event XML definition files and event configuration files:

Event name Definition file Configuration file
Bugzilla report_Bugzilla.xml report_Bugzilla.conf
Logger report_Logger.xml report_Logger.conf
Analyze C/C++ Crash analyze_CCpp.xml analyze_CCpp.conf
Local GNU Debugger analyze_LocalGDB.xml analyze_LocalGDB.conf
Retrace Server analyze_RetraceServer.xml analyze_RetraceServer.conf
Analyze VM core analyze_VMcore.xml analyze_VMcore.conf
Collect GConf configuration collect_GConf.xml collect_GConf.conf
Collect system-wide vim configuration files collect_vimrc_system.xml collect_vimrc_system.conf
Collect your vim configuration files collect_vimrc_user.xml collect_vimrc_user.conf
Collect .xsession-errors collect_xsession_errors.xml collect_xsession_errors.conf
Post report post_report.xml post_report.conf
Kerneloops.org report_Kerneloops.xml report_Kerneloops.conf
Mailx report_Mailx.xml report_Mailx.conf
Report uploader report_Uploader.xml report_Uploader.conf
uReport report_uReport.xml report_uReport.conf

By default the ABRT complains about missing configuration if any of mandatory options is not configured. Mandatory option is option not marked as ‘Allow empty’. Run the following command to obtain the list of mandatory options:

xmllint --xpath "/event/options/option[allow-empty!='yes']/@name" $EVENT_XML_FILE \
        | sed 's/name="\([^ ]*\)"/\1\n/g'