[deployment-guide/comm-rel: 139/727] modified ABRT chapter
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 12:35:55 UTC 2010
commit 27d3454476c4bd8c6541dc2d70ddbcc90b30d9bb
Author: Martin Prpic <mprpic at redhat.com>
Date: Fri Jul 23 16:40:44 2010 +0200
modified ABRT chapter
en-US/ABRT.xml | 163 +++++++++++++++++++++++++------------------------------
1 files changed, 74 insertions(+), 89 deletions(-)
---
diff --git a/en-US/ABRT.xml b/en-US/ABRT.xml
index b7d0a76..465fe55 100644
--- a/en-US/ABRT.xml
+++ b/en-US/ABRT.xml
@@ -1,28 +1,25 @@
<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter
- id="ch-abrt">
+<chapter id="ch-abrt">
<title>ABRT</title>
<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, through its modular, plugin-oriented architecture, <application>ABRT</application> provides a number of ways to transmit the crash information to a relevant issue tracker, such as Bugzilla. <application>ABRT</application>'s various plugins provide the capability of capturing crash information from applications written in the C, C++ and Python languages, as well as the necessary communication backends for issue trackers to which it can report.</para>
- <para>The <application>ABRT</application> application consists of the <systemitem
- class="daemon">abrtd</systemitem> system service, <application>abrt-applet</application>, which runs in the user's Notification Area, and the <application>Automatic Bug-Reporting Tool</application> GUI application.</para>
- <mediaobject
- id="mediaobj-ABRT-Main_Window">
+ <para>The <application>ABRT</application> application consists of the <systemitem class="daemon">abrtd</systemitem> system service, <application>abrt-applet</application>, which runs in the user's Notification Area, and the <application>Automatic Bug-Reporting Tool</application> GUI application.</para>
+ <mediaobject id="mediaobj-ABRT-Main_Window">
<imageobject>
- <imagedata
- align="center"
- fileref="images/ABRT-Main_Window.png"
- format="PNG" />
+ <imagedata align="center" fileref="images/ABRT-Main_Window.png" format="PNG" />
</imageobject>
<caption>
<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>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: <command>yum list all |grep abrt</command>.</para>
<!-- <itemizedlist>
<listitem>
@@ -66,51 +63,43 @@
</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>
+ <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>
</screen>
<para>
- <application>ABRT</application> is typically configured to start up at boot time. You can ensure that the <systemitem
- class="daemon">abrtd</systemitem> daemon is running by issuing the command:</para>
+ <application>ABRT</application> is typically configured to start up at boot time. You can ensure that the <systemitem class="daemon">abrtd</systemitem> daemon is running by issuing the command:</para>
<screen>~]# <command>service abrtd status</command>
abrt (pid 1559) is running...</screen>
- <para>If you receive <computeroutput>abrt is stopped</computeroutput>, you can start the <systemitem
- class="daemon">abrtd</systemitem>
+ <para>If you receive <computeroutput>abrt is stopped</computeroutput>, you can start the <systemitem class="daemon">abrtd</systemitem>
daemon by running, as root:</para>
<screen>~]# <command>service abrtd start</command>
Starting abrt daemon: [ OK ]</screen>
- <para>You can ensure that the <systemitem
- class="daemon">abrtd</systemitem> service initializes at startup time by running the <command>chkconfig abrtd on</command> command as root.</para>
+ <para>You can ensure that the <systemitem class="daemon">abrtd</systemitem> service initializes at startup time by running the <command>chkconfig abrtd on</command> command as root.</para>
<para>
<application>ABRT</application>'s applet can be started by hand by running the <command>abrt-applet</command> program as a normal user when logged into your desktop session, or by arranging for it to be started when the GUI session is initialized. For example, on the GNOME desktop, this can be configured in <menuchoice><guimenu>System</guimenu>
<guimenuitem>Preferences</guimenuitem>
<guimenuitem>Preferences</guimenuitem>
<guimenuitem>Startup Applications</guimenuitem>
</menuchoice>.</para>
- <mediaobject
- id="mediaobj-ABRT-Notification_Area_alarm_icon">
+ <mediaobject id="mediaobj-ABRT-Notification_Area_alarm_icon">
<imageobject>
- <imagedata
- align="center"
- fileref="images/ABRT-Notification_Area_alarm_icon.png"
- width="29"
- format="PNG" />
+ <imagedata align="center" fileref="images/ABRT-Notification_Area_alarm_icon.png" width="29" format="PNG" />
</imageobject>
<caption>
<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>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>
</section>
- <section
- id="configuring">
+ <section id="configuring">
<title>Configuring ABRT</title>
<para>
<application>ABRT</application>'s main configuration file is <filename>/etc/abrt/abrt.conf</filename>. <application>ABRT</application> plugins can be configured through their config files, located in the <filename>/etc/abrt/plugins/</filename> directory.</para>
- <para>After changing and saving the <filename>abrt.conf</filename> configuration file, you must restart the <systemitem
- class="daemon">abrtd</systemitem> daemon—as root—for the new settings to take effect:</para>
+ <para>After changing and saving the <filename>abrt.conf</filename> configuration file, you must restart the <systemitem class="daemon">abrtd</systemitem> daemon—as root—for the new settings to take effect:</para>
<screen>~]# <command>service abrtd restart</command>
</screen>
<para>The following configuration directives are currently supported in <filename>/etc/abrt/abrt.conf</filename>.</para>
@@ -132,7 +121,8 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
</varlistentry>
<varlistentry>
- <term>ProcessUnpackaged = <replaceable><yes/no></replaceable></term>
+ <term>ProcessUnpackaged = <replaceable><yes/no></replaceable>
+ </term>
<listitem>
<para>
This directive tells <application>ABRT</application> whether to process crashes in executables that do now belong to any package.
@@ -140,7 +130,8 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
</varlistentry>
<varlistentry>
- <term>BlackListedPaths = <filename>/usr/share/doc/*</filename>, <filename >*/example*</filename></term>
+ <term>BlackListedPaths = <filename>/usr/share/doc/*</filename>, <filename>*/example*</filename>
+ </term>
<listitem>
<para>
This directive includes blacklisted executable paths. Crashes in executables in these paths will be ignored by <application>ABRT</application>.
@@ -205,8 +196,7 @@ Starting abrt daemon: [ OK ]</screen>
</term>
<listitem>
<para>The <computeroutput>[ Cron ]</computeroutput> section of <filename>abrt.conf</filename> allows you to specify the exact time, or elapsed amount of time between, when <application>ABRT</application> should run a certain action, such as scanning for kernel oopses or performing file transfers. You can list further actions to run by appending them to the end of this section.</para>
- <example
- id="ex-_Cron__section_of__etc_abrt_abrt.conf">
+ <example id="ex-_Cron__section_of__etc_abrt_abrt.conf">
<title>[ Cron ] section of /etc/abrt/abrt.conf</title>
<screen># Which Action plugins to run repeatedly
[ Cron ]
@@ -220,25 +210,23 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
+ </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 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>
+ <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 machines and sent to a dedicated machine for further processing. This is useful when an administrator does not want to log into hundreds of machines and check for crashes found by <application>ABRT</application> manually.
- </para>
- <para>
- The steps to configure <application>ABRT</application> central management are:
+ <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 machines and sent to a dedicated machine for further processing. This is useful when an administrator does not want to log into hundreds of machines 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>).
+ </para>
+ <para>
+ The steps to configure <application>ABRT</application>'s centralized crash collection are:
</para>
<para>
Complete the following steps on a dedicated machine ("server machine"):
@@ -250,7 +238,7 @@ Starting abrt daemon: [ OK ]</screen>
</para>
<note>
<title>Note</title>
- <para>
+ <para>
The abrt user is a user named "abrt". This user is used by <systemitem class="daemon">abrtd</systemitem> for various things, for example, as the owner of <filename>/var/spool/abrt*</filename> directories.
</para>
</note>
@@ -312,17 +300,14 @@ ActionsAndReporters = ReportUploader
</listitem>
<listitem>
<para>
- TBD: * If you want crash dumps to be sent to server only on the admin's
- command via abrt-cli or abrt-gui, set ReportUploader to be a reporter
- plugin for every crash type you are interested in. For example,
- if you want all crash typed to use it, then edit /etc/abrt/abrt.conf,
- [AnalyzerActionsAndReporters] section to look like this:
-
- Kerneloops = ReportUploader
- CCpp = ReportUploader
- Python = ReportUploader
+ Setting the <parameter>ReportUploader</parameter> to be a reporter plugin for a specific crash type in the <literal>[AnalyzerActionsAndReporters]</literal> section of the <filename>/etc/abrt/abrt.conf</filename> configuration file will require user interaction before the crash dump is sent to the server machine. The user will be required to run <application>abrt-cli</application> or <application>abrt-gui</application> and instruct <systemitem class="daemon">abrtd</systemitem> to report the crash and send it to the server machine. For example, if you want all crash types to use this method, edit your <filename>/etc/abrt/abrt.conf</filename> configuration file in the following way:
</para>
- </listitem>
+<screen>
+Kerneloops = ReportUploader
+CCpp = ReportUploader
+Python = ReportUploader
+</screen>
+ </listitem>
</itemizedlist>
<para>
After completing this configuration process, the basic setup is finished. To test that this setup works properly, use the <command>kill -SEGV</command> command to terminate a process on a client machine. Check that the crash was detected by <application>ABRT</application> on the client machine (this can be checked by examining the appropriate syslog file), copied to the server machine, unpacked on the server machine and can be seen and acted upon using <command>abrt-cli</command> or <command>abrt-gui</command> on the server machine.
@@ -333,23 +318,23 @@ ActionsAndReporters = ReportUploader
<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 1000 Mb.
+ 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 1000 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 machine and the server machine have significantly different sets of installed packages.
+ 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 machine and the server machine have significantly different sets of installed packages.
</para>
</listitem>
</itemizedlist>
- </section>
- <section>
- <title>Using the Command Line Interface</title>
- <para>Crashes detected by <application>ABRT</application> can be viewed, reported, and deleted using the command line interface.</para>
+ </section>
<section>
- <title>Viewing Crashes</title>
- <para>To get a list of all crashes, simply enter <command>abrt-cli --list</command> or <command>abrt-cli -l</command>:</para>
- <screen>
+ <title>Using the Command Line Interface</title>
+ <para>Crashes detected by <application>ABRT</application> can be viewed, reported, and deleted using the command line interface.</para>
+ <section>
+ <title>Viewing Crashes</title>
+ <para>To get a list of all crashes, simply enter <command>abrt-cli --list</command> or <command>abrt-cli -l</command>:</para>
+ <screen>
~]# <command>abrt-cli --list</command>
0.
UID : 500
@@ -366,32 +351,32 @@ ActionsAndReporters = ReportUploader
Crash Time : Tue 20 Jul 2010 03:22:00 PM CEST
Crash Count: 1
</screen>
- <para>This output contains basic information for every crash. The <computeroutput>UID:</computeroutput> field shows the ID of the user which ran the program that caused the crash. It is useful when <command>abrt-cli</command> is executed with superuser privileges and it lists crashes from all users. The <computeroutput>Package</computeroutput> field shows the name and version of the &MAJOROS; package that contains the program, and the <computeroutput>Executable</computeroutput> field shows the location of the binary or script that crashed. The <computeroutput>Crash Count</computeroutput> field indicates how many times the same crash happened.</para>
- </section>
- <section>
- <title>Reporting Crashes</title>
- <para>To report certain crash, you enter <command>abrt-cli <replaceable>--report/-r</replaceable> <UUID></command>, where <varname>UUID</varname> is a field from <command>abrt-cli <replaceable>--list/-l</replaceable></command>. You do not need to remember the exact <varname>UUID</varname>; either use a mouse to copy and paste it, or enter a unique prefix and press <keycap function="tab"><ENTER></keycap>.</para>
-<screen>
+ <para>This output contains basic information for every crash. The <computeroutput>UID:</computeroutput> field shows the ID of the user which ran the program that caused the crash. It is useful when <command>abrt-cli</command> is executed with superuser privileges and it lists crashes from all users. The <computeroutput>Package</computeroutput> field shows the name and version of the &MAJOROS; package that contains the program, and the <computeroutput>Executable</computeroutput> field shows the location of the binary or script that crashed. The <computeroutput>Crash Count</computeroutput> field indicates how many times the same crash happened.</para>
+ </section>
+ <section>
+ <title>Reporting Crashes</title>
+ <para>To report certain crash, you enter <command>abrt-cli <replaceable>--report/-r</replaceable> <UUID></command>, where <varname>UUID</varname> is a field from <command>abrt-cli <replaceable>--list/-l</replaceable>
+ </command>. You do not need to remember the exact <varname>UUID</varname>; either use a mouse to copy and paste it, or enter a unique prefix and press <keycap function="tab"><ENTER></keycap>.</para>
+ <screen>
~]# <command>abrt-cli --report 480</command>
- <keycap
- function="tab"><ENTER></keycap>
+ <keycap function="tab"><ENTER></keycap>
>> Starting report creation...
</screen>
- <para>
- <application>ABRT</application> analyzes the crash and creates a report about it. This might take a while. When the report is ready, <command>abrt-cli</command> opens a text editor with the content of the report. You can see what is being reported, and you can fill in instructions on how to reproduce the crash and other comments. You should also check the backtrace, because the backtrace might be sent to a public server and viewed by anyone, depending on the plugin settings.</para>
+ <para>
+ <application>ABRT</application> analyzes the crash and creates a report about it. This might take a while. When the report is ready, <command>abrt-cli</command> opens a text editor with the content of the report. You can see what is being reported, and you can fill in instructions on how to reproduce the crash and other comments. You should also check the backtrace, because the backtrace might be sent to a public server and viewed by anyone, depending on the plugin settings.</para>
<note>
- <title>Preferred Text Editor</title>
- <para>You can choose which text editor is used to check the reports. <command>abrt-cli</command> uses the editor defined in the <envar>ABRT_EDITOR</envar> environment variable. If the variable is not defined, it checks the <envar>VISUAL</envar> and <envar>EDITOR</envar> variables. If none of these variables is set, <command>vi</command> is used. You can set the preferred editor in your <filename>.bashrc</filename> configuration file. For example, if you prefer GNU Emacs, add the following line to the file:</para>
- <screen>
+ <title>Preferred Text Editor</title>
+ <para>You can choose which text editor is used to check the reports. <command>abrt-cli</command> uses the editor defined in the <envar>ABRT_EDITOR</envar> environment variable. If the variable is not defined, it checks the <envar>VISUAL</envar> and <envar>EDITOR</envar> variables. If none of these variables is set, <command>vi</command> is used. You can set the preferred editor in your <filename>.bashrc</filename> configuration file. For example, if you prefer GNU Emacs, add the following line to the file:</para>
+ <screen>
export <varname>VISUAL</varname>=<userinput>emacs</userinput>
</screen>
- </note>
- <para>When you are done with the report, save your changes and close the editor. You will be asked if you want to send the report. Respond <keycap>Y</keycap> to send the report or <keycap>N</keycap> to cancel it.</para>
+ </note>
+ <para>When you are done with the report, save your changes and close the editor. You will be asked if you want to send the report. Respond <keycap>Y</keycap> to send the report or <keycap>N</keycap> to cancel it.</para>
+ </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>
+ </section>
</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>
- </section>
- </section>
-</chapter>
+ </chapter>
More information about the docs-commits
mailing list