[deployment-guide/comm-rel: 394/727] fixed stuff and added new section
Jaromir Hradilek
jhradile at fedoraproject.org
Tue Oct 19 12:57:51 UTC 2010
commit d6f91e321c1248bc06f72d5ed12e35e7579b0206
Author: Martin Prpic <mprpic at redhat.com>
Date: Mon Aug 16 17:26:11 2010 +0200
fixed stuff and added new section
en-US/ABRT.xml | 299 ++++++++++++++++++++++++++++++++++++--------------------
1 files changed, 192 insertions(+), 107 deletions(-)
---
diff --git a/en-US/ABRT.xml b/en-US/ABRT.xml
index ce008e4..3017421 100644
--- a/en-US/ABRT.xml
+++ b/en-US/ABRT.xml
@@ -6,7 +6,7 @@
<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 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.
+ <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 crash data to a relevant issue tracker, such as Bugzilla. Reporting crash data to a relevant issue tracker 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>
@@ -28,12 +28,14 @@
</listitem>
<listitem>
<para>
- <application>abrt-cli</application>, the command line application with functionality similar to <application>abrt-gui</application>
+ <application>abrt-cli</application>, the command line interface 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>.
+ <guisubmenu>System Tools</guisubmenu>
+ <guimenuitem>Automatic Bug Reporting Tool</guimenuitem>
+ </menuchoice>.
</para>
<mediaobject id="mediaobj-ABRT-Main_Window">
<imageobject>
@@ -93,11 +95,12 @@
<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> to run in the Notification Area of your desktop session.
<note>
<title>Note: Installing the <application>ABRT</application> packages</title>
- <para>In order to use <application>ABRT</application>, first ensure the <command>abrt-desktop</command> package is installed on your system by running, as root:
+ <para>In order to use <application>ABRT</application>, first ensure the <command>abrt-desktop</command> package is installed on your system by running, as root:
</para>
- <screen>~]# <command>yum install abrt-desktop</command></screen>
- <para>For more information on installing packages with Yum, refer to <xref linkend="sec-Installing"/>.</para>
- </note>
+ <screen>~]# <command>yum install abrt-desktop</command>
+ </screen>
+ <para>For more information on installing packages with Yum, refer to <xref linkend="sec-Installing"/>.</para>
+ </note>
You can check whether <application>ABRT</application> is installed by running:</para>
<screen>~]$ <command>yum install abrt-desktop</command>
</screen>
@@ -127,13 +130,17 @@ Starting abrt daemon: [ OK ]</screen>
</caption>
</mediaobject>
<para>When a crash is detected and saved, a broadcast <systemitem>D-Bus</systemitem> message is sent 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>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="plugins-and-sending-crash-reports">
- <title>Plugins and Sending Crash Reports</title>
+ <section id="abrt-plugins">
+ <title>
+ <application>ABRT</application> Plugins</title>
<para>
- <application>ABRT</application> offers a variety of analyzer plugins and reporter plugins. Each of these plugins is described in detail in the following two sections. Not all of the plugins mentioned in the following sections are installed by default. To view all available plugins, run the following command:
+ <application>ABRT</application> offers a variety of analyzer plugins and reporter plugins. These plugins are described in the following two sections. Not all of the plugins mentioned in the following sections are installed by default. To view all available plugins, run the following command:
<screen>
<command>]$ yum list all |grep abrt-plugin-*</command>
</screen>
@@ -141,15 +148,14 @@ Starting abrt daemon: [ OK ]</screen>
<section id="analyzer-plugins">
<title>Analyzer Plugins</title>
<para>
- These plugins serve as analyzers and crash information collectors for specific types of crashes. For example, the <application>Kerneloops</application> analyzer plugin checks for crashes in the kernel only. These plugins can be turned off and on in their corresponding configuration files placed in the <filename>/etc/abrt/plugins/</filename> directory. However, turning off one of these plugins will cause the associated crashes to not be caught by <application>ABRT</application>. The following is a list of all analyzer plugins.
+ These plugins serve as analyzers and crash information collectors for specific types of crashes. For example, the <application>Kerneloops</application> analyzer plugin checks for crashes in the kernel only. These plugins can be enabled/disabled from loading at start-up in their corresponding configuration files placed in the <filename>/etc/abrt/plugins/</filename> directory. The following is a list of all analyzer plugins.
</para>
<variablelist>
- <title>Analyzer Plugins</title>
<varlistentry>
<term>Kerneloops</term>
<listitem>
<para>
- This plugin checks for crashes in the kernel and consequently collects kernel crash information. It can be enabled/disabled in the <filename>/etc/abrt/plugins/Kerneloops.conf</filename> file.
+ — checks for crashes in the kernel and consequently collects kernel crash information. It can be enabled/disabled from loading at start-up in the <filename>/etc/abrt/plugins/Kerneloops.conf</filename> file.
</para>
</listitem>
</varlistentry>
@@ -157,7 +163,7 @@ Starting abrt daemon: [ OK ]</screen>
<term>Python</term>
<listitem>
<para>
- This plugin checks for crashes in Python programs and consequently collects the crash information. It can be enabled/disabled in the <filename>/etc/abrt/plugins/Python.conf</filename> file.
+ — checks for crashes in Python programs and consequently collects the crash information. It can be enabled/disabled from loading at start-up in the <filename>/etc/abrt/plugins/Python.conf</filename> file.
</para>
</listitem>
</varlistentry>
@@ -165,7 +171,7 @@ Starting abrt daemon: [ OK ]</screen>
<term>CCpp</term>
<listitem>
<para>
- This plugin checks for crashes in C and C++ programs and consequently collects the crash information. It can be enabled/disabled in the <filename>/etc/abrt/plugins/CCpp.conf</filename> file.
+ — checks for crashes in C and C++ programs and consequently collects the crash information. It can be enabled/disabled from loading at start-up in the <filename>/etc/abrt/plugins/CCpp.conf</filename> file.
</para>
</listitem>
</varlistentry>
@@ -174,10 +180,9 @@ Starting abrt daemon: [ OK ]</screen>
<section id="reporter-plugins">
<title>Reporter Plugins</title>
<para>
- These plugins are used to gather the crash data acquired by the analyzer plugins, combine the data with any user input (such as comments about the cras, reproducibility, etc.), and provide a specific output. Each of these plugins can be configured in its corresponding configuration file placed in the <filename>/etc/abrt/plugins/</filename> directory or in the <application>ABRT</application> GUI application (for more information on reporter plugin configuration in the <application>ABRT</application> GUI application, refer to <xref linkend="configuring-plugins-in-the-gui"/>).
+ These plugins gather the crash data acquired by the analyzer plugins, combine the data with any user input (such as comments about the crash, reproducibility, etc.), and provide a specific output. Each of these plugins is configurable in its corresponding configuration file placed in the <filename>/etc/abrt/plugins/</filename> directory or in the <application>ABRT</application> GUI application (for more information on reporter plugin configuration in the <application>ABRT</application> GUI application, refer to <xref linkend="configuring-plugins-in-the-gui"/>).
</para>
<variablelist>
- <title>Reporter Plugins</title>
<varlistentry>
<term>RHTSupport</term>
<listitem>
@@ -190,7 +195,7 @@ Starting abrt daemon: [ OK ]</screen>
<term>MailX</term>
<listitem>
<para>
- A simple reporter plugin which sends a crash report via the <application>mailx</application> utility to a specified email address.
+ — sends a crash report via the <application>mailx</application> utility to a specified email address.
</para>
</listitem>
</varlistentry>
@@ -198,7 +203,7 @@ Starting abrt daemon: [ OK ]</screen>
<term>Report Uploader</term>
<listitem>
<para>
- This plugin reports crashes into an anonymous <systemitem class="protocol">FTP</systemitem> site associated with a ticketing system.
+ — reports crashes into an anonymous <systemitem class="protocol">FTP</systemitem> site associated with a ticketing system.
</para>
</listitem>
</varlistentry>
@@ -206,11 +211,11 @@ Starting abrt daemon: [ OK ]</screen>
<term>Bugzilla</term>
<listitem>
<para>
- This plugin reports crashes into Bugzilla in the form of Bugzilla bugs.
+ — reports crashes into Bugzilla in the form of Bugzilla bugs.
</para>
<note>
<title>Note</title>
- <para>
+ <para>
The use of the Bugzilla plugin to report crashes into Bugzilla in the form of bugs is strongly discouraged. Please use the RHTSupport plugin to report crashes into the Red Hat Ticketing System instead.
</para>
</note>
@@ -220,7 +225,7 @@ Starting abrt daemon: [ OK ]</screen>
<term>Logger</term>
<listitem>
<para>
- A simple reporter plugin which creates a crash report and saves it to a specified local file.
+ — creates a crash report and saves it to a specified local file.
</para>
</listitem>
</varlistentry>
@@ -229,12 +234,13 @@ Starting abrt daemon: [ OK ]</screen>
<section id="configuring-plugins-in-the-gui">
<title>Plugin Configuration in the GUI</title>
<para>
- The system-wide plugin configuration in the <filename>/etc/abrt/plugins/*.conf</filename> configuration files may be overridden on a per-user basis.
- Each of the plugins specified in section <xref linkend="reporter-plugins"/> can be configured in the <application>ABRT</application> GUI application. Open the plugins window by clicking <menuchoice><guimenu>Edit</guimenu><guisubmenu>Plugins</guisubmenu></menuchoice>. This window shows a list of all installed plugins. You can also view each of the plugins' details by selecting one and expanding the <guimenu>Plugin Details</guimenu> tab. When you click on one of the configurable plugins, the <guibutton>Configure</guibutton> button can be clicked and you will be able to configure your desired plugin. If you change any of the plugins' parameters, they are saved in the Gnome keyring and will be used in the future GUI sessions.
+ You can override the system-wide plugin configuration in the <filename>/etc/abrt/plugins/*.conf</filename> configuration files on a per-user basis. Each of the plugins specified in section <xref linkend="reporter-plugins"/> can be configured in the <application>ABRT</application> GUI application. Open the plugins window by clicking <menuchoice><guimenu>Edit</guimenu>
+ <guisubmenu>Plugins</guisubmenu>
+ </menuchoice>. This window shows a list of all installed plugins. You can also view each of the plugins' details by selecting one and expanding <guimenu>Plugin Details</guimenu>. When you select one of the configurable plugins, you can click the <guibutton>Configure plugin</guibutton> button and you will be able to configure your desired plugin. If you change any of the plugins' parameters, they are saved in the Gnome keyring and will be used in the future GUI sessions.
</para>
<note>
<title>Note</title>
- <para>
+ <para>
All of the <filename>/etc/abrt/plugins/*.conf</filename> configuration files are world readable and are meant to be used as global settings. Thus, it is not advisable to store usernames, passwords or any other sensitive data in them. The per-user settings (set in the GUI application and readable by the owner of $HOME only) are stored in the Gnome keyring or can be stored in a text file in <filename>$HOME/.abrt/*.conf</filename> for use in <command>abrt-cli</command>.
</para>
</note>
@@ -243,17 +249,13 @@ Starting abrt daemon: [ OK ]</screen>
</para>
<mediaobject id="mediaobj-abrt-plugins">
<imageobject>
- <imagedata
- align="center"
- fileref="images/ABRT-plugins.png"
- format="PNG"/>
- </imageobject>
- <caption>
- <para>ABRT Plugins</para>
- </caption>
+ <imagedata align="center" fileref="images/ABRT-plugins.png" format="PNG"/>
+ </imageobject>
+ <caption>
+ <para>ABRT Plugins</para>
+ </caption>
</mediaobject>
<variablelist>
- <title>Configurable Plugins</title>
<varlistentry>
<term>RHTSupport</term>
<listitem>
@@ -286,7 +288,7 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
</itemizedlist>
<para>
- When the <guilabel>Send Binary Data</guilabel> option is checked, the crash report email will also contain all binary files associated with the crash in an attachement. The core dump file is also sent as an attachement.
+ When the <guilabel>Send Binary Data</guilabel> option is checked, the crash report email will also contain all binary files associated with the crash in an attachment. The core dump file is also sent as an attachment.
</para>
</listitem>
</varlistentry>
@@ -299,7 +301,7 @@ Starting abrt daemon: [ OK ]</screen>
<itemizedlist>
<listitem>
<para>
- <guilabel>Customer</guilabel> — specifies customer's identification
+ <guilabel>Customer</guilabel> — specifies customer's identification.
</para>
</listitem>
<listitem>
@@ -309,17 +311,17 @@ Starting abrt daemon: [ OK ]</screen>
</listitem>
<listitem>
<para>
- <guilabel>URL</guilabel> — specifies the URL of the issue tracker used to collect crash reports
+ <guilabel>URL</guilabel> — specifies the URL of the issue tracker used to collect crash reports.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Retry count</guilabel> — specifies the number of retries should an upload fail
+ <guilabel>Retry count</guilabel> — specifies the number of retries should an upload fail.
</para>
</listitem>
<listitem>
<para>
- <guilabel>Retry delay</guilabel> — specifies the number or seconds between two retries
+ <guilabel>Retry delay</guilabel> — specifies the number or seconds between two retries.
</para>
</listitem>
</itemizedlist>
@@ -380,7 +382,77 @@ Starting abrt daemon: [ OK ]</screen>
</variablelist>
</section>
</section>
- <section>
+ <section id="generating-backtrace">
+ <title>Generating Backtraces</title>
+ <para>
+ In order to analyze a reported crash, developers need as much details about the crash as possible. A <firstterm>stack backtrace</firstterm> is an important source of information when a crash in a binary program (caught by the <command>CCpp</command> analyzer plugin) occurs.
+ </para>
+ <para>
+ <application>ABRT</application> is configured to generate a backtrace whenever a crash is reported through the <application>ABRT</application> GUI application or the <application>ABRT</application> command line interface.
+ </para>
+ <para>
+ <application>ABRT</application> completes the following steps to generate a backtrace:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ It examines the core dump (which consists of the recorded contents of the memory of an application at a specific time), which is saved in the crash dump file. From this file, <application>ABRT</application> extracts the information about the crashed binary program and information about every loaded dynamic library.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It queries <application>Yum</application> to determine which <command>debuginfo</command> packages correspond to all the files extracted from the crash dump. This is the first potentially slow operation. <application>Yum</application> may need to refresh the <parameter>filelists</parameter> of various repositories in order to find the correct package names. This process may take up to few minutes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It downloads the needed <command>debuginfo</command> packages, and extracts and saves the <command>debuginfo</command> files. In order to speed up future backtrace generation, <command>debuginfo</command> files are cached in the <filename>/var/cache/abrt-di</filename> directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It generates a backtrace using <application>GDB</application> (the GNU Debugger) and saves it into the crash dump file.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You can change the following backtrace generation parameters in the <filename>/etc/abrt/plugins/CCpp.conf</filename> file:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>Backtrace = <replaceable><yes/no></replaceable></command> — enables/disables backtrace generation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>BacktraceRemotes = <replaceable><yes/no></replaceable></command> — for more information about this parameter, refer to <xref linkend="configuring-centralized-crash-collection"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>InstallDebugInfo = <replaceable><yes/no></replaceable></command> — enables/disables the installation of <command>debuginfo</command> packages (useful if your network is not available or it is firewalled).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>ReadonlyLocalDebugInfoDirs = /path1:/path2:...</command> — specifies the paths of local repositories (available, for example, through a network mount) that contain pre-downloaded <command>debuginfo</command> packages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>DebugInfoCacheMB = <constant>4000</constant></command> — specifies the maximum size of the cached <command>debuginfo</command> packages in the <filename>/var/cache/abrt-di</filename> directory.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section id="troubleshooting">
+ <title>Troubleshooting Backtrace Generation</title>
+ <para>
+ In some cases, a long delay in the <application>ABRT</application> GUI application occurs after choosing a crash and pressing the <guibutton>Report</guibutton> button. In this case, open the <guibutton>Details</guibutton> in the <guilabel>Generating backtrace</guilabel> window and examine the provided messages. [***TO_BE_EXPANDED***]
+ </para>
+ </section>
+ </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>
@@ -427,7 +499,8 @@ 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 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>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.
@@ -503,7 +576,8 @@ export <varname>VISUAL</varname>=<userinput>emacs</userinput>
</optional>
</term>
<listitem>
- <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 <xref linkend="plugins-and-sending-crash-reports"/></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 <xref linkend="abrt-plugins"/>
+ </para>
</listitem>
</varlistentry>
</variablelist>
@@ -530,7 +604,7 @@ export <varname>VISUAL</varname>=<userinput>emacs</userinput>
</varlistentry>
</variablelist>
<para>
- 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. All these options can also be configured through the <command>abrt-gui</command> application (for more information on plugin configuration refer to <xref linkend="plugins-and-sending-crash-reports"/>).
+ 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. All these options can also be configured through the <command>abrt-gui</command> application (for more information on plugin configuration refer to <xref linkend="abrt-plugins"/>).
</para>
<variablelist>
<title>[ Cron ] Section Directives</title>
@@ -558,108 +632,100 @@ export <varname>VISUAL</varname>=<userinput>emacs</userinput>
<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 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>).
+ You can 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:
</para>
- <para>
- Complete the following steps on a dedicated system ("server system"):
- </para>
- <itemizedlist>
+ <orderedlist>
<listitem>
- <para>
+ <para>Complete the following steps on a dedicated system ("server system"):</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 <systemitem class="username">abrt</systemitem> user.
</para>
- <note>
- <title>Note</title>
- <para>
+ <note>
+ <title>Note</title>
+ <para>
When the <package>abrt-desktop</package> package is installed, it creates a new system user and and a group, both named <systemitem class="username">abrt</systemitem>. This user is used by the <systemitem class="daemon">abrtd</systemitem> daemon for various things, for example, as the owner:group of <filename>/var/spool/abrt/*</filename> directories.
</para>
- </note>
- </listitem>
- <listitem>
- <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>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
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>
+ <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>. 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>
- </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>
- 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>
+ <para>
+ It is advisable to check whether your upload method works. For more information, refer to <xref linkend="testing-upload-method"/>.
+ </para>
+ </listitem>
+ <listitem>
+ <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>
+ </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>
+ </listitem>
+ </itemizedlist>
</listitem>
- </itemizedlist>
- <para>
- Complete the following steps on every client system which will use the central management method:
- </para>
- <itemizedlist>
<listitem>
- <para>
+ <para>Complete the following steps on every client system 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://USERNAME:PASSWORD@SERVERNAME/var/spool/abrt-upload/
</screen>
- </para>
- </listitem>
- <listitem>
- <para>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
To automatically send the crash reports to the server system 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>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
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 system. 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 system. 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>
- <screen>
+ <screen>
Kerneloops = ReportUploader
CCpp = ReportUploader
Python = ReportUploader
</screen>
+ </listitem>
+ </itemizedlist>
</listitem>
- </itemizedlist>
- <bridgehead>Testing ABRT's Crash Detection</bridgehead>
+ </orderedlist>
+ <section>
+ <title>Testing ABRT's Crash Detection</title>
<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:
@@ -669,6 +735,25 @@ Python = ReportUploader
~]$ 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, 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>
+ </para></section>
+ <section id="testing-upload-method">
+ <title>Testing the Upload Method</title>
+ <para>
+ Test your upload method from a client 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>
+ Check whether <filename>TESTFILE</filename> appeared in the correct directory on the server system.
+ </para>
+ </section>
</section>
</chapter>
More information about the docs-commits
mailing list