[deployment-guide/comm-rel: 111/727] modified the ABRT chapter

Jaromir Hradilek jhradile at fedoraproject.org
Tue Oct 19 12:33:31 UTC 2010


commit 669ba254a57b7622c102d17b89e190a6f9e008d6
Author: Martin Prpic <mprpic at redhat.com>
Date:   Thu Jul 22 17:12:32 2010 +0200

    modified the ABRT chapter

 en-US/ABRT.xml                    |  205 +++++++++++++++++++++++++++++-------
 en-US/images/ABRT-Main_Window.png |  Bin 70322 -> 62743 bytes
 2 files changed, 165 insertions(+), 40 deletions(-)
---
diff --git a/en-US/ABRT.xml b/en-US/ABRT.xml
index 8e27e8a..b7d0a76 100644
--- a/en-US/ABRT.xml
+++ b/en-US/ABRT.xml
@@ -23,8 +23,8 @@
       </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. Here are descriptions of some of the <application>ABRT</application> packages:</para>
-    <itemizedlist>
+    <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>
         <para>
           <package>abrt-desktop</package> — <application>ABRT</application>'s main package. Installing this package will install <application>ABRT</application> and also pull in several addon packages. Note that this package is installed by default on &MAJOROS;.</para>
@@ -54,14 +54,6 @@
         <para>
           <package>abrt-plugin-ticketuploader</package> — this package contains the plugin that uploads tickets created by <application>ABRT</application> to a specified URL.</para>
       </listitem>
-      <!-- jmoskovcak: abrt-plugin-runapp is not really used for anything
-      <listitem>
-        <para>abrt-plugin-runapp</para>
-      </listitem>-->
-      <!--<listitem>
-        <para>
-          <package>abrt-plugin-logger</package> — supports logging <command>abrtd</command> messages to a specifiable file location.</para>
-      </listitem>-->
       <listitem>
         <para>
           <package>abrt-addon-ccpp</package> — this plugin provides support for catching crashes in C and C++ binary programs.</para>
@@ -70,12 +62,12 @@
         <para>
           <package>abrt-addon-python</package> — this plugin provides support for catching crashes in programs written in the Python programming language.</para>
       </listitem>
-    </itemizedlist>
+    </itemizedlist> -->
   </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 ensure that <application>ABRT</application> is installed by running, as root:</para>
+        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>~]#&#160;<command>yum install abrt-desktop</command>
     </screen>
     <para>
@@ -136,20 +128,44 @@ Starting abrt daemon:                                      [  OK  ]</screen>
           </optional>
         </term>
         <listitem>
-          <para>Crashes in packages listed after the <parameter>BlackList</parameter> option will not be handled by <application>ABRT</application>. If you want <application>ABRT</application> to ignore other packages, list them here separated by commas.</para>
+          <para>Crashes in packages listed after the <parameter>BlackList</parameter> directive will not be handled by <application>ABRT</application>. If you want <application>ABRT</application> to ignore other packages, list them here separated by commas.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>ProcessUnpackaged = <replaceable>&lt;yes/no&gt;</replaceable></term>
+        <listitem>
+          <para>
+            This directive tells <application>ABRT</application> whether to process crashes in executables that do now belong to any package.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <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>.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>Database = SQLite3</term>
         <listitem>
-          <para>This option instructs <application>ABRT</application> to store its crash data in the <application>SQLite3</application> database. Other databases are not currently supported. However, <application>ABRT</application>'s plugin architecture allows for future support for alternative databases.</para>
+          <para>This directive instructs <application>ABRT</application> to store its crash data in the <application>SQLite3</application> database. Other databases are not currently supported. However, <application>ABRT</application>'s plugin architecture allows for future support for alternative databases.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>#WatchCrashdumpArchiveDir = /var/spool/abrt-upload</term>
+        <listitem>
+          <para>
+            This directive is commented out by default. Enable (uncomment) it if you want <systemitem class="daemon">abrtd</systemitem> to auto-unpack crashdump tarballs which appear in the specified directory — in this case <filename>/var/spool/abrt-upload</filename> — (for example, uploaded via <systemitem class="service">ftp</systemitem>, <systemitem class="service">scp</systemitem>, etc.). You must ensure that whatever directory you specify in this directive exists and is writable for <systemitem class="daemon">abrtd</systemitem>. <systemitem class="daemon">abrtd</systemitem> will not create it automatically.
+          </para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>MaxCrashReportsSize = <replaceable>&lt;size_in_megabytes&gt;</replaceable>
         </term>
         <listitem>
-          <para>This option sets the amount of storage space, in megabytes, used by <application>ABRT</application> to store all crash information from all users. The default setting is <constant>1000</constant>&#160;MB. Once the quota specified here has been met, <application>ABRT</application> will no longer catch and save program crash information.</para>
+          <para>This option sets the amount of storage space, in megabytes, used by <application>ABRT</application> to store all crash information from all users. The default setting is <constant>1000</constant>&#160;MB. Once the quota specified here has been met, <application>ABRT</application> will continue catching crashes, and in order to make room for the new crashes, it will delete the oldest and largest ones.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -171,13 +187,13 @@ Starting abrt daemon:                                      [  OK  ]</screen>
       <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 should 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 C or C++ program crashes occur, both the TicketUploader and Bugzilla reporters should run.</para>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -204,8 +220,8 @@ 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 ]
@@ -216,45 +232,154 @@ Starting abrt daemon:                                      [  OK  ]</screen>
         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: 
+      </para>
+      <para>
+        Complete the following steps on a dedicated machine ("server machine"):
+      </para>
+      <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.  
+          </para>
+          <note>
+            <title>Note</title>
+              <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>
+        </listitem>
+        <listitem>
+          <para>
+             In the <filename>/etc/abrt/abrt.conf</filename> configuration file, set the <varname>WatchCrashdumpArchiveDir</varname> directive to the following:
+<screen>
+WatchCrashdumpArchiveDir = /var/spool/abrt-upload
+</screen>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Set up your preferred upload mechanism, for example <systemitem class="daemon">ftp</systemitem>, <systemitem class="daemon">scp</systemitem>. For more information on how to configure <systemitem class="daemon">ftp</systemitem>, refer to <xref linkend="ch-FTP"/>. For more information on how to configure <systemitem class="daemon">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 "USERNAME" and the password is "PASSWORD".
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Test from another machine that your upload method. For example, upload a file using the interactive <systemitem class="daemon">ftp</systemitem> client:
+          </para>
+          <screen>
+~]$ ftp
+ftp> open SERVERNAME
+Name: USERNAME
+Password: PASSWORD
+ftp> put TESTFILE
+ftp> quit
+          </screen>
+          <para>
+            Check if the "TESTFILE" file appeared in the desired directory on your server machine.
+          </para>
+        </listitem>
+      </itemizedlist>
+      <para>
+        Complete the following steps on every machine ("client machine") which will use the central management method:
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+             Modify the <filename>/etc/abrt/plugins/ReportUploader.conf</filename> configuration file so that the <application>ReportUploader</application> plugin knows where to copy the saved crash reports in the following way:
+<screen>
+Enabled = yes
+Upload = yes
+URL = ftp://user:password@server/ 
+</screen>
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+             To automatically send the crash reports to the server machine immediately after the crash occurs, is detected, and saved, set the <varname>ActionsAndReporters</varname> directive in the <filename>/etc/abrt/abrt.conf</filename> configuration file to the following:
+<screen>
+ActionsAndReporters = ReportUploader 
+</screen>
+          </para>
+        </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 
+          </para>
+        </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.
+      </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 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.
+          </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>
       <title>Viewing Crashes</title>
-      <para>To get a list of all crashes, simply enter <command>abrt-cli --get-list</command>:</para>
+      <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 --get-list</command>
+~]# <command>abrt-cli --list</command>
 0.
-    UID        : 501
-    UUID       : d074c2882400b3ff245415e676ed53f22bb8e7b5
-    Package    : gnome-packagekit-2.28.2-0.1.20091030git.fc12
-    Executable : /usr/bin/gpk-application
-    Crash Time : Wed 18 Nov 2009 12:07:40 PM CET
-    Crash Count: 2
+   UID        : 500
+   UUID       : 784b06666020e9f43718d99bf2649f19b4f251a9
+   Package    : bash-4.1.2-3.el6
+   Executable : /bin/bash
+   Crash Time : Tue 20 Jul 2010 03:22:52 PM CEST
+   Crash Count: 2
 1.
-    UID        : 501
-    UUID       : 52d0d2f64f0b07fb0e626ecdfa4ac4faadc38258
-    Package    : gnome-commander-1.3-0.3.git_D20090929T1100_13dev.fc12
-    Executable : /usr/libexec/gnome-commander/gnome-commander
-    Crash Time : Wed 18 Nov 2009 04:58:46 PM CET
-    Crash Count: 1
+   UID        : 500
+   UUID       : 48007b98d65cca4530d99a564379e2609169239d
+   Package    : coreutils-8.4-9.el6
+   Executable : /bin/sleep
+   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 --report &lt;UUID&gt;</command>, where <varname>UUID</varname> is a field from <command>abrt-cli --get-list</command>. You do not need to remember the exact <varname>UUID</varname>; either use a mouse to copy and paste it, or use bash completion (write first few characters of the <varname>UUID</varname> and press <keycap
-          function="tab">&lt;TAB&gt;</keycap>).</para>
-      <screen>
-~]# <command>abrt-cli --report 52d</command>
+      <para>To report certain crash, you enter <command>abrt-cli <replaceable>--report/-r</replaceable> &lt;UUID&gt;</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">&lt;ENTER&gt;</keycap>.</para>
+<screen>
+~]# <command>abrt-cli --report 480</command>
         <keycap
-          function="tab">&lt;TAB&gt;</keycap>
-~]# <command>abrt-cli --report 52d0d2f64f0b07fb0e626ecdfa4ac4faadc38258</command>
+          function="tab">&lt;ENTER&gt;</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>
-      <note>
+        <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>
diff --git a/en-US/images/ABRT-Main_Window.png b/en-US/images/ABRT-Main_Window.png
index 4e5b8b9..a3a4b0f 100644
Binary files a/en-US/images/ABRT-Main_Window.png and b/en-US/images/ABRT-Main_Window.png differ


More information about the docs-commits mailing list