[deployment-guide/comm-rel: 261/727] improved the ABRT chapter
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 12:46:29 UTC 2010
commit 939ae6bc24431ae5f7d844aeab22a18eb088c36d
Author: Martin Prpic <mprpic at redhat.com>
Date: Wed Aug 4 15:06:54 2010 +0200
improved the ABRT chapter
en-US/ABRT.xml | 137 +++++++++++++++++++++++++++++++++----------------------
1 files changed, 82 insertions(+), 55 deletions(-)
---
diff --git a/en-US/ABRT.xml b/en-US/ABRT.xml
index e60cd54..af7b5b0 100644
--- a/en-US/ABRT.xml
+++ b/en-US/ABRT.xml
@@ -6,9 +6,35 @@
<section>
<title>Overview</title>
<para>
- <application>ABRT</application> is the <application>Automatic Bug-Reporting Tool</application>. <application>ABRT</application> consists of a daemon that runs silently in the background most of the time. It springs into action when an application crashes. It then collects the relevant crash data such as a core file if there is one, the crashing application's command line parameters, and other contextual puzzle pieces of forensic utility. Finally, <application>ABRT</application> is capable of transmitting the crash data to a relevant issue tracker, such as Bugzilla. This can be configured to happen automatically at every detected crash, or crash dumps can be stored locally, reviewed, transmitted, and deleted manually by a user. <application>ABRT</application>'s various plugins analyze crash data from applications written in the C, C++ and Python language, as well as report crashes to relevant issue trackers.
+ <application>ABRT</application> is the <application>Automatic Bug-Reporting Tool</application>. <application>ABRT</application> consists of a daemon that runs silently in the background most of the time. It springs into action when an application crashes. It then collects the relevant crash data such as a core file if there is one, the crashing application's command line parameters, and other contextual puzzle pieces of forensic utility. Finally, <application>ABRT</application> is capable of reporting the crash data to a relevant issue tracker, such as Bugzilla. This can be configured to happen automatically at every detected crash, or crash dumps can be stored locally, reviewed, reported, and deleted manually by a user. <application>ABRT</application>'s various plugins analyze crash data from applications written in the C, C++ and Python language, as well as report crashes to relevant issue trackers.
+ </para>
+ <para>The <application>ABRT</application> package consists of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <systemitem class="daemon">abrtd</systemitem>, the system service
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>abrt-applet</application>, which runs in the user's Notification Area
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>abrt-gui</application>, the GUI application that shows collected crash dumps and allows you to edit, report, and delete them
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <application>abrt-cli</application>, the command line application with functionality similar to <application>abrt-gui</application>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>You can open the <application>ABRT</application> GUI application by clicking <menuchoice><guimenu>Applications</guimenu>
+ <guisubmenu>System Tools</guisubmenu><guimenuitem>Automatic Bug Reporting Tool</guimenuitem></menuchoice>.
</para>
- <para>The <application>ABRT</application> package consists of the <systemitem class="daemon">abrtd</systemitem> system service, <application>abrt-applet</application>, which runs in the user's Notification Area, the <application>Automatic Bug-Reporting Tool</application> GUI application, and a command line application.</para>
<mediaobject id="mediaobj-ABRT-Main_Window">
<imageobject>
<imagedata align="center" fileref="images/ABRT-Main_Window.png" format="PNG" />
@@ -17,14 +43,10 @@
<para>Automatic Bug Reporting Tool Main Window</para>
</caption>
</mediaobject>
- <para>You can open the <application>ABRT</application> GUI window by clicking <menuchoice><guimenu>Applications</guimenu>
- <guisubmenu>System Tools</guisubmenu>
- <guimenuitem>Automatic Bug Reporting Tool</guimenuitem>
- </menuchoice>.</para>
<para>A number of additional packages can be installed to provide <application>ABRT</application> plugins and addons. To view all the available <application>ABRT</application> packages, type the following command:
<screen>
<command>yum list all |grep abrt</command>
-</screen>
+ </screen>
</para>
<!-- <itemizedlist>
<listitem>
@@ -68,8 +90,8 @@
</section>
<section>
<title>Installing and Running ABRT</title>
- <para>By default, <application>ABRT</application> should be installed on your system, the <systemitem class="daemon">abrtd</systemitem> daemon configured to run at boot time, and <application>abrt-applet</application> is running in the Notification Area of your desktop session. You can check whether <application>ABRT</application> is installed by running, as root:</para>
- <screen>~]# <command>yum install abrt-desktop</command>
+ <para>By default, <application>ABRT</application> should be installed on your system, the <systemitem class="daemon">abrtd</systemitem> daemon configured to run at boot time, and <application>abrt-applet</application> is running in the Notification Area of your desktop session. You can check whether <application>ABRT</application> is installed by running:</para>
+ <screen>~]$ <command>rpm -qa | grep abrt</command>
</screen>
<para>
<application>ABRT</application> is typically configured to start up at boot time. You can check that the <systemitem class="daemon">abrtd</systemitem> daemon is running by issuing the command:</para>
@@ -93,11 +115,9 @@ Starting abrt daemon: [ OK ]</screen>
<para>The ABRT alarm icon</para>
</caption>
</mediaobject>
- <para>When <command>abrt-applet</command> detects a crash, it displays a red alarm icon in the Notifcation Area. You can open the GUI application by clicking on this icon.</para>
- <para>Alternatively, you can open the <application>ABRT</application> GUI window by clicking <menuchoice><guimenu>Applications</guimenu>
- <guisubmenu>System Tools</guisubmenu>
- <guimenuitem>Automatic Bug Reporting Tool</guimenuitem>
- </menuchoice>.</para>
+ <para>When <command>abrt-applet</command> detects and saves a crash, a <systemitem>D-Bus</systemitem> message is sent to <command>abrt-applet</command> about this crash. If <command>abrt-applet</command> is running, it receives this message and displays a red alarm icon in the Notification Area. You can open the GUI application by clicking on this icon.</para>
+ <para>Alternatively, you can open the <application>ABRT</application> GUI application by clicking <menuchoice><guimenu>Applications</guimenu> <guisubmenu>System Tools</guisubmenu><guimenuitem>Automatic Bug Reporting Tool</guimenuitem></menuchoice>.
+ </para>
</section>
<section id="configuring">
<title>Configuring ABRT</title>
@@ -164,31 +184,33 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
</varlistentry>
<varlistentry>
- <term>ActionsAndReporters = SOSreport</term>
+ <term>ActionsAndReporters = SOSreport, <optional><replaceable><additional_plugins></replaceable>
+ </optional>
+ </term>
<listitem>
- <para>This option tells <application>ABRT</application> to run the <command>sosreport</command> command immediately after a crash. You can turn this behavior off by commenting out this line. For further fine-tuning, you can add <userinput>SOSreport</userinput> to either the <parameter>CCpp</parameter> or <parameter>Python</parameter> options to make <application>ABRT</application> run <command>sosreport</command> after C and C++ or Python application crashes, respectively.</para>
+ <para>This option tells <application>ABRT</application> to run the specified plugin(s) immediately after a crash is detected and saved. For example, the <userinput>SOSreport</userinput> plugin runs the <systemitem>sosreport</systemitem> tool which adds the data collected by it to the created crash dump. You can turn this behavior off by commenting out this line. For further fine-tuning, you can add <userinput>SOSreport</userinput> (or any other specified plugin) to either the <parameter>CCpp</parameter> or <parameter>Python</parameter> options to make <application>ABRT</application> run <command>sosreport</command> (or any other specified plugin) after any C and C++ or Python applications crash, respectively. For more information on various Action and Reporter plugins, refer to TBD</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>[ AnalyzerActionsAndReporters ] Section Directives</title>
- <para>This section allows you to associate certain analyzer actions and reporter actions to run when <application>ABRT</application> catches kernel oopses or crashes in C, C++ or Python programs. The order of actions and reporters is important.</para>
+ <para>This section allows you to associate certain analyzer actions and reporter actions to run when <application>ABRT</application> catches kernel oopses or crashes in C, C++ or Python programs. The actions and reporters specified in any of the directives below will run only if you run <command>abrt-gui</command> or <command>abrt-cli</command> and report the crash that occurred. The order of actions and reporters is important.</para>
<varlistentry>
<term>Kerneloops = TicketUploader, Bugzilla</term>
<listitem>
- <para>This directive specifies that, for kernel oopses, the TicketUploader and Bugzilla reporters should run.</para>
+ <para>This directive specifies that, for kernel oopses, the TicketUploader and Bugzilla reporters will be run.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CCpp = TicketUploader, Bugzilla</term>
<listitem>
- <para>This directive specifies that, when C or C++ program crashes occur, both the TicketUploader and Bugzilla reporters should run.</para>
+ <para>This directive specifies that, when C or C++ program crashes occur, both the TicketUploader and Bugzilla reporters will be run.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Python = TicketUploader, Bugzilla</term>
<listitem>
- <para>This directive specifies that, when C or C++ program crashes occur, both the TicketUploader and Bugzilla reporters should run.</para>
+ <para>This directive specifies that, when Python program crashes occur, both the TicketUploader and Bugzilla reporters will be run.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -217,17 +239,19 @@ Starting abrt daemon: [ OK ]</screen>
</section>
<section>
<title>Plugins and Sending Crash Reports</title>
- <para>The <literal>[AnalyzerActionsAndReporters]</literal> section in <filename>abrt.conf</filename> specifies which plugins are to be used to transmit crash data. As of version 1.0.0, the default <filename>abrt.conf</filename> contains:</para>
- <screen>[ AnalyzerActionsAndReporters ]
- Kerneloops = KerneloopsReporter
- CCpp = Bugzilla, Logger
- Python = Bugzilla, Logger</screen>
+ <para>The <literal>[AnalyzerActionsAndReporters]</literal> section in <filename>abrt.conf</filename> specifies which plugins are to be used to report crash data. As of version 1.0.0, the default <filename>abrt.conf</filename> contains:</para>
+ <screen>
+[ AnalyzerActionsAndReporters ]
+Kerneloops = KerneloopsReporter
+CCpp = Bugzilla, Logger
+Python = Bugzilla, Logger
+</screen>
<para>These lines indicate that kernel oopses are to be reported to the <ulink url="kerneloops.org"/> site, and that both binary crashes and python crashes are to be reported to Bugzilla and to a local text file. Each of these destinations' details can be specified in the corresponding <filename>plugins/*.conf</filename> file. For example, <filename>plugins/Bugzilla.conf</filename> specifies which Bugzilla URL to use (set to <ulink url="https://bugzilla.redhat.com/"/> by default), the user's login name, password for logging in to the Bugzilla site, etc.</para>
</section>
<section id="configuring-centralized-crash-collection">
<title>Configuring Centralized Crash Collection</title>
<para>
- It is possible to set up <application>ABRT</application> so that crash reports are collected from multiple systems and sent to a dedicated system for further processing. This is useful when an administrator does not want to log into hundreds of systems and check for crashes found by <application>ABRT</application> manually. In order to use this method, you need to install the <application>abrt-plugin-reportuploader</application> plugin (<command>yum install abrt-plugin-reportuploader</command>).
+ It is possible to set up <application>ABRT</application> so that crash reports are collected from multiple systems and sent to a dedicated system for further processing. This is useful when an administrator does not want to log into hundreds of systems and manually check for crashes found by <application>ABRT</application>. In order to use this method, you need to install the <application>abrt-plugin-reportuploader</application> plugin (<command>yum install abrt-plugin-reportuploader</command>).
</para>
<para>
The steps to configure <application>ABRT</application>'s centralized crash collection are:
@@ -238,7 +262,7 @@ Starting abrt daemon: [ OK ]</screen>
<itemizedlist>
<listitem>
<para>
- Create a directory to which you want the crash reports to be uploaded to. Usually, <filename>/var/spool/abrt-upload/</filename> is used (the rest of the document assumes you are using <filename>/var/spool/abrt-upload/</filename>). Make sure this directory is writable by the abrt user.
+ Create a directory to which you want the crash reports to be uploaded to. Usually, <filename>/var/spool/abrt-upload/</filename> is used (the rest of the document assumes you are using <filename>/var/spool/abrt-upload/</filename>). Make sure this directory is writable by the <systemitem class="username">abrt</systemitem> user.
</para>
<note>
<title>Note</title>
@@ -260,23 +284,38 @@ WatchCrashdumpArchiveDir = /var/spool/abrt-upload/
Determine your preferred upload mechanism; for example, <systemitem class="protocol">FTP</systemitem> or <systemitem class="protocol">SCP</systemitem>. For more information on how to configure <systemitem class="protocol">FTP</systemitem>, refer to <xref linkend="ch-FTP"/>. For more information on how to configure <systemitem class="protocol">SCP</systemitem>, refer to <xref linkend="s2-ssh-clients-scp"/>.
</para>
<para>
- For security reasons, make sure that uploads can only be performed by a specific user and with a password. The rest of the document assumes that the username used for uploads is <systemitem class="username">USERNAME</systemitem> and the password is <literal>PASSWORD</literal>.
+ For security reasons, make sure that uploads can only be performed by a specific user and with a password. The rest of the document assumes that the username used for uploads is <systemitem class="username">USERNAME</systemitem> and the password is <literal>PASSWORD</literal>. If you do not already have a suitable username which can be used to perform uploads under, you may use the <systemitem class="username">abrt</systemitem> user which already exists on every system where <application>ABRT</application> is installed.
</para>
</listitem>
- <listitem>
- <para>
- Test your upload method from a different system to ensure that it works. For example, upload a file using the interactive <systemitem class="protocol">FTP</systemitem> client:
- </para>
- <screen>
+ </itemizedlist>
+ <para>
+ Test your upload method from a different system to ensure that it works. For example, upload a file using the interactive <systemitem class="protocol">FTP</systemitem> client:
+ </para>
+ <screen>
~]$ ftp
ftp> open SERVERNAME
Name: USERNAME
Password: PASSWORD
+ftp> cd /var/spool/abrt-upload
+250 Operation successful
ftp> put TESTFILE
ftp> quit
</screen>
- <para>
+ <para>
Ensure that <filename>TESTFILE</filename> appeared in the correct directory on the server system.
+ </para>
+ <para>
+ It is advisable to check and modify the following parameters if needed:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <parameter>MaxCrashReportsSize</parameter> directive (in <filename>/etc/abrt/abrt.conf</filename>) needs to be set to a larger value if the expected volume of crash data is larger than the default <constant>1000</constant> MB.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <parameter>ProcessUnpackaged</parameter> directive (in <filename>/etc/abrt/abrt.conf</filename>) needs to be set to <replaceable>yes</replaceable> and the <parameter>BacktraceRemotes</parameter> (in <filename>/etc/abrt/plugins/CCpp.conf</filename>) needs to be set to <replaceable>no</replaceable> if the client system and the server system have significantly different sets of installed packages.
</para>
</listitem>
</itemizedlist>
@@ -290,7 +329,7 @@ ftp> quit
<screen>
Enabled = yes
Upload = yes
-URL = ftp://USERNAME:PASSWORD@SERVERNAME/
+URL = ftp://USERNAME:PASSWORD@SERVERNAME/var/spool/abrt-upload/
</screen>
</para>
</listitem>
@@ -313,30 +352,16 @@ Python = ReportUploader
</screen>
</listitem>
</itemizedlist>
- <para>
- It is advisable to check and modify the following parameters if needed:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The <parameter>MaxCrashReportsSize</parameter> directive (in <filename>/etc/abrt/abrt.conf</filename>) needs to be set to a larger value if the expected volume of crash data is larger than the default <constant>1000</constant> MB.
- </para>
- </listitem>
- <listitem>
- <para>
- The <parameter>ProcessUnpackaged</parameter> directive (in <filename>/etc/abrt/abrt.conf</filename>) needs to be set to <replaceable>yes</replaceable> and the <parameter>BacktraceRemotes</parameter> (in <filename>/etc/abrt/plugins/CCpp.conf</filename>) needs to be set to <replaceable>no</replaceable> if the client system and the server system have significantly different sets of installed packages.
- </para>
- </listitem>
- </itemizedlist>
<bridgehead>Testing ABRT's Crash Detection</bridgehead>
<para>
- After completing all the steps of the configuration process, the basic setup is finished. To test that this setup works properly use the <command>kill -s SEGV <replaceable>PID</replaceable></command> command to terminate a process on a client system. For example, start a <systemitem class="process">sleep</systemitem> process and terminate it with the <command>kill</command> command in the following way:
+ After completing all the steps of the configuration process, the basic setup is finished. To test that this setup works properly use the <command>kill -s SEGV <replaceable>PID</replaceable>
+ </command> command to terminate a process on a client system. For example, start a <systemitem class="process">sleep</systemitem> process and terminate it with the <command>kill</command> command in the following way:
<screen>
~]$ sleep 100 &
[1] 2823
~]$ kill -s SEGV 2823
</screen>
- <application>ABRT</application> should detect a crash shortly after executing the <command>kill</command> command. Check that the crash was detected by <application>ABRT</application> on the client system (this can be checked by examining the appropriate syslog file), copied to the server system, unpacked on the server system and can be seen and acted upon using <command>abrt-cli</command> or <command>abrt-gui</command> on the server system.
+ <application>ABRT</application> should detect a crash shortly after executing the <command>kill</command> command. Check that the crash was detected by <application>ABRT</application> on the client system (this can be checked by examining the appropriate syslog file, by running the <command>abrt-cli --list --full</command> command, or by examining the crash dump created in the <filename>/var/spool/abrt</filename> directory), copied to the server system, unpacked on the server system and can be seen and acted upon using <command>abrt-cli</command> or <command>abrt-gui</command> on the server system.
</para>
</section>
<section>
@@ -386,9 +411,11 @@ export <varname>VISUAL</varname>=<userinput>emacs</userinput>
</section>
<section>
<title>Deleting Crashes</title>
- <para>If you know that you do not want to report a certain crash, you can delete it from the crash list. To delete a certain crash, enter the command: <command>abrt-cli --delete <replaceable><UUID></replaceable>
- </command>.
- </para>
+ <para>If you know that you do not want to report a certain crash dump, you can delete it from the crash list. To delete a certain crash dump, enter the command: <command>abrt-cli --delete <replaceable><UUID></replaceable></command>.
+ </para>
+ <para>
+ Note that <application>ABRT</application> performs a detection of duplicate crashes by comparing new crashes with all locally saved crashes. For a repeating crash, <application>ABRT</application> requires you to act upon it only once. However, if you delete the crash dump of that crash, the next time this specific crash occurs, <application>ABRT</application> will treat it as a new crash: <application>ABRT</application> will alert you about it, prompt you to fill in a description, and report it. This can be redundant, therefore, deleting a crash is not advisable.
+ </para>
</section>
</section>
</chapter>
More information about the docs-commits
mailing list