Merge lp:~petermatulis/serverguide/review_reporting-bugs into lp:serverguide/trunk

Proposed by Peter Matulis on 2014-07-18
Status: Merged
Approved by: Doug Smythies on 2014-07-20
Approved revision: 207
Merged at revision: 210
Proposed branch: lp:~petermatulis/serverguide/review_reporting-bugs
Merge into: lp:serverguide/trunk
Diff against target: 463 lines (+158/-206)
1 file modified
serverguide/C/reporting-bugs.xml (+158/-206)
To merge this branch: bzr merge lp:~petermatulis/serverguide/review_reporting-bugs
Reviewer Review Type Date Requested Status
Doug Smythies 2014-07-18 Approve on 2014-07-20
Review via email: mp+227398@code.launchpad.net

Description of the change

Same as the one pushed to Utopic.

To post a comment you must log in.
Doug Smythies (dsmythies) wrote :

Peter, it looks good thanks. I couldn't submit a test bug report against the "Ubuntu Server Guide" because it is not a package. I did submit one against "docbook" and it is pending, and I hope it will delete by itself after some time when I don't finish it.

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'serverguide/C/reporting-bugs.xml'
2--- serverguide/C/reporting-bugs.xml 2013-03-23 22:09:27 +0000
3+++ serverguide/C/reporting-bugs.xml 2014-07-18 20:40:54 +0000
4@@ -14,74 +14,57 @@
5 <title>Reporting Bugs in Ubuntu Server Edition</title>
6
7 <para>
8- While the Ubuntu Project attempts to release software with as few
9- bugs as possible, they do occur. You can help fix these bugs by
10- reporting ones that you find to the project. The Ubuntu Project
11- uses <ulink url="https://launchpad.net/">Launchpad</ulink>
12- to track its bug reports. In order to file a bug
13- about Ubuntu Server on Launchpad, you will need to
14- <ulink url="https://help.launchpad.net/YourAccount/NewAccount">create
15- an account</ulink>.
16+ The Ubuntu Project, and thus Ubuntu Server, uses <ulink url="https://launchpad.net/">Launchpad</ulink>
17+ as its bugtracker. In order to file a bug, you will need a Launchpad account. <ulink url="https://help.launchpad.net/YourAccount/NewAccount">Create
18+ one here</ulink> if necessary.
19 </para>
20
21- <sect2 id="reporting-bugs-ubuntu-bug" status="review">
22- <title>Reporting Bugs With ubuntu-bug</title>
23-
24- <para>
25- The preferred way to report a bug is with the
26- <application>ubuntu-bug</application> command. The ubuntu-bug
27- tool gathers information about the system useful to developers in
28- diagnosing the reported problem that will then be included in the
29- bug report filed on Launchpad. Bug reports in Ubuntu need to be
30- filed against a specific software package, thus the name of the
31- package that the bug occurs in needs to be given to ubuntu-bug:
32- </para>
33-
34-<screen>
35-<command>ubuntu-bug PACKAGENAME</command>
36-</screen>
37-
38- <para>
39- For example, to file a bug against the openssh-server package, you would do:
40- </para>
41-
42-<screen>
43-<command>ubuntu-bug openssh-server</command>
44-</screen>
45-
46- <para>
47- You can specify either a binary package or the source package
48- for ubuntu-bug. Again using openssh-server as an example,
49- you could also generate the report against the source package
50- for openssh-server, openssh:
51- </para>
52-
53-<screen>
54-<command>ubuntu-bug openssh</command>
55+ <sect2 id="reporting-bugs-apport-cli" status="review">
56+ <title>Reporting Bugs With apport-cli</title>
57+
58+ <para>
59+ The preferred way to report a bug is with the <application>apport-cli</application> command. It must be invoked on the machine affected by the bug
60+ because it collects information from the system on which it is being run and publishes it to the bug report on Launchpad. Getting that information to
61+ Launchpad can therefore be a challenge if the system is not running a desktop environment in order to use a browser (common with servers) or if it does
62+ not have Internet access. The steps to take in these situations are described below.
63+ </para>
64+
65+ <note>
66+ <para>
67+ The commands <application>apport-cli</application> and <application>ubuntu-bug</application> should give the same results on a CLI server.
68+ The latter is actually a symlink to <application>apport-bug</application> which is intelligent enough to know whether a desktop environment is in use and
69+ will choose <application>apport-cli</application> if not. Since server systems tend to be CLI-only apport-cli was chosen from the outset in this guide.
70+ </para>
71+ </note>
72+
73+ <para>
74+ Bug reports in Ubuntu need to be filed against a specific software package, so the name of the
75+ package (source package or program name/path) affected by the bug needs to be supplied to apport-cli:
76+ </para>
77+
78+<screen>
79+<command>apport-cli PACKAGENAME</command>
80 </screen>
81
82 <note>
83 <para>
84- See <xref linkend="package-management"/>
85- for more information about packages in Ubuntu.
86+ See <xref linkend="package-management"/> for more information about packages in Ubuntu.
87 </para>
88 </note>
89
90 <para>
91- The ubuntu-bug command will gather information about the system in
92- question, possibly including information specific to the specified
93- package, and then ask you what you would like to do with collected
94- information:
95+ Once apport-cli has finished gathering information you will be asked what to do with it. For
96+ instance, to report a bug in vim:
97 </para>
98
99 <screen>
100-<command>ubuntu-bug postgresql</command>
101+<command>apport-cli vim</command>
102
103 *** Collecting problem information
104
105 The collected information can be sent to the developers to improve the
106 application. This might take a few minutes.
107-..........
108+...
109
110 *** Send problem report to the developers?
111
112@@ -89,117 +72,115 @@
113 automatically opened web browser.
114
115 What would you like to do? Your options are:
116- S: Send report (1.7 KiB)
117+ S: Send report (2.8 KB)
118 V: View report
119 K: Keep report file for sending later or copying to somewhere else
120+ I: Cancel and ignore future crashes of this program version
121 C: Cancel
122-Please choose (S/V/K/C):
123+Please choose (S/V/K/I/C):
124 </screen>
125
126 <para>
127- The options available are:
128+ The first three options are described below:
129 </para>
130
131 <para>
132 <itemizedlist>
133 <listitem>
134- <para><emphasis role="bold">Send Report</emphasis> Selecting
135- Send Report submits the collected information to Launchpad as
136- part of the process of filing a bug report. You will be
137- given the opportunity to describe the situation that led up to
138- the occurrence of the bug.
139+ <para><emphasis role="bold">Send:</emphasis>
140+ submits the collected information to Launchpad as part of the process
141+ of filing a new bug report. You will be given the opportunity to describe
142+ the bug in your own words.
143 </para>
144
145 <screen>
146+
147 *** Uploading problem information
148
149 The collected information is being sent to the bug tracking system.
150 This might take a few minutes.
151-91%
152+94%
153
154 *** To continue, you must visit the following URL:
155
156-https://bugs.launchpad.net/ubuntu/+source/postgresql-8.4/+filebug/kc6eSnTLnLxF8u0t3e56EukFeqJ?
157-
158-You can launch a browser now, or copy this URL into a browser on another
159-computer.
160+ https://bugs.launchpad.net/ubuntu/+source/vim/+filebug/09b2495a-e2ab-11e3-879b-68b5996a96c8?
161+
162+You can launch a browser now, or copy this URL into a browser on another computer.
163+
164
165 Choices:
166 1: Launch a browser now
167 C: Cancel
168-Please choose (1/C):
169-</screen>
170-
171- <para>
172- If you choose to start a browser, by default the text based web
173- browser <application>w3m</application> will be used to finish filing
174- the bug report. Alternately, you can copy the given URL to a
175- currently running web browser.
176- </para>
177- </listitem>
178-
179- <listitem>
180- <para>
181- <emphasis role="bold">View Report</emphasis> Selecting View
182- Report causes the collected information to be displayed to
183- the terminal for review.
184- </para>
185-
186-<screen>
187-Package: postgresql 8.4.2-2
188-PackageArchitecture: all
189-Tags: lucid
190-ProblemType: Bug
191-ProcEnviron:
192- LANG=en_US.UTF-8
193- SHELL=/bin/bash
194-Uname: Linux 2.6.32-16-server x86_64
195-Dependencies:
196- adduser 3.112ubuntu1
197- base-files 5.0.0ubuntu10
198- base-passwd 3.5.22
199- coreutils 7.4-2ubuntu2
200-...
201-</screen>
202-
203- <para>
204- After viewing the report, you will be brought back to the same
205- menu asking what you would like to do with the report.
206- </para>
207- </listitem>
208-
209- <listitem>
210- <para>
211- <emphasis role="bold">Keep Report File</emphasis> Selecting Keep
212- Report File causes the gathered information to be written to
213- a file. This file can then be used to later file a bug report
214- or transferred to a different Ubuntu system for reporting.
215- To submit the report file, simply give it as an argument to
216- the ubuntu-bug command:
217+Please choose (1/C): <userinput>1</userinput>
218+</screen>
219+
220+ <para>
221+ The browser that will be used when choosing '1' will be the one known on the system as
222+ <application>www-browser</application> via the
223+ <ulink url="http://manpages.ubuntu.com/manpages/en/man8/update-alternatives.8.html">
224+ Debian alternatives system</ulink>. Examples of text-based browsers to install include <application>links</application>,
225+ <application>elinks</application>, <application>lynx</application>, and <application>w3m</application>.
226+ You can also manually point an existing browser at the given URL.
227+ </para>
228+ </listitem>
229+
230+ <listitem>
231+ <para>
232+ <emphasis role="bold">View:</emphasis>
233+ displays the collected information on the screen for review. This can
234+ be a lot of information. Press 'Enter' to scroll by screenful. Press 'q'
235+ to quit and return to the choice menu.
236+ </para>
237+ </listitem>
238+
239+ <listitem>
240+ <para>
241+ <emphasis role="bold">Keep:</emphasis>
242+ writes the collected information to disk. The resulting file can be later used to
243+ file the bug report, typically after transferring it to another Ubuntu system.
244 </para>
245
246 <screen>
247 What would you like to do? Your options are:
248- S: Send report (1.7 KiB)
249+ S: Send report (2.8 KB)
250 V: View report
251 K: Keep report file for sending later or copying to somewhere else
252+ I: Cancel and ignore future crashes of this program version
253 C: Cancel
254-Please choose (S/V/K/C): <userinput>k</userinput>
255-Problem report file: /tmp/apport.postgresql.v4MQas.apport
256-
257-<command>ubuntu-bug /tmp/apport.postgresql.v4MQas.apport</command>
258-
259-*** Send problem report to the developers?
260-...
261-</screen>
262- </listitem>
263-
264- <listitem>
265- <para>
266- <emphasis role="bold">Cancel</emphasis> Selecting
267- Cancel causes the collected information to be discarded.
268- </para>
269- </listitem>
270+Please choose (S/V/K/I/C): <userinput>k</userinput>
271+Problem report file: /tmp/apport.vim.1pg92p02.apport
272+</screen>
273+
274+ <para>
275+ To report the bug, get the file onto an internet-enabled Ubuntu system and apply apport-cli
276+ to it. This will cause the menu to appear immediately (the information is already collected).
277+ You should then press 's' to send:
278+ </para>
279+
280+<screen>
281+<command>apport-cli apport.vim.1pg92p02.apport</command>
282+</screen>
283+
284+<para>
285+To directly save a report to disk (without menus) you can do:
286+
287+<screen>
288+<command>apport-cli vim --save apport.vim.test.apport</command>
289+</screen>
290+
291+Report names should end in <emphasis>.apport</emphasis> .
292+</para>
293+
294+ <note>
295+ <para>
296+ If this internet-enabled system is non-Ubuntu/Debian, apport-cli is not available so the
297+ bug will need to be created manually. An apport report is also not to be included as an
298+ attachment to a bug either so it is completely useless in this scenario.
299+ </para>
300+ </note>
301+
302+ </listitem>
303+
304 </itemizedlist>
305 </para>
306 </sect2>
307@@ -207,89 +188,58 @@
308 <sect2 id="apport-crash-catching" status="review">
309 <title>Reporting Application Crashes</title>
310
311- <para>
312- The software package that provides the ubuntu-bug utility,
313- <application>apport</application>, can be configured to trigger
314- when applications crash. This is disabled by default, as capturing
315- a crash can be resource intensive depending on how much memory
316- the application that crashed was using as apport captures and
317- processes the core dump.
318- </para>
319-
320- <para>
321- Configuring apport to capture information about
322- crashing applications requires a couple of steps. First,
323- <application>gdb</application> needs to be installed; it is not
324- installed by default in Ubuntu Server Edition.
325- </para>
326-
327-<screen>
328-<command>sudo apt-get install gdb</command>
329-</screen>
330-
331- <para>
332- See <xref linkend="package-management"/>
333- for more information about managing packages in Ubuntu.
334- </para>
335-
336- <para>
337- Once you have ensured that gdb is installed, open the file
338- <filename>/etc/default/apport</filename> in your text editor,
339- and change the <emphasis>enabled</emphasis> setting to be
340- <emphasis role="bold">1</emphasis> like so:
341- </para>
342-
343-<programlisting>
344-# set this to 0 to disable apport, or to 1 to enable it
345-# you can temporarily override this with
346-# sudo service apport start force_start=1
347-enabled=<userinput>1</userinput>
348-
349-# set maximum core dump file size (default: 209715200 bytes == 200 MB)
350-maxsize=209715200
351-</programlisting>
352-
353- <para>
354- Once you have completed editing
355- <filename>/etc/default/apport</filename>,
356- start the apport service:
357- </para>
358-
359-<screen>
360-<command>sudo start apport</command>
361-</screen>
362-
363- <para>
364- After an application crashes, use the
365- <application>apport-cli</application> command to search for the
366- existing saved crash report information:
367- </para>
368+ <para>
369+ The software package that provides the apport-cli utility, <application>apport</application>,
370+ can be configured to automatically capture the state of a crashed application. This
371+ is enabled by default (in <filename>/etc/default/apport</filename>).
372+ </para>
373+
374+ <para>
375+ After an application crashes, if enabled, apport will store a crash report under <filename>/var/crash</filename>:
376+ </para>
377+
378+<screen>
379+-rw-r----- 1 peter whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
380+</screen>
381+
382+ <para>
383+ Use the <application>apport-cli</application> command without arguments to process any pending crash reports. It
384+ will offer to report them one by one.
385+ </para>
386
387 <screen>
388 <command>apport-cli</command>
389
390-*** dash closed unexpectedly on 2010-03-11 at 21:40:59.
391+*** Send problem report to the developers?
392
393-If you were not doing anything confidential (entering passwords or other
394-private information), you can help to improve the application by
395-reporting
396-the problem.
397+After the problem report has been sent, please fill out the form in the
398+automatically opened web browser.
399
400 What would you like to do? Your options are:
401- R: Report Problem...
402+ S: Send report (153.0 KB)
403+ V: View report
404+ K: Keep report file for sending later or copying to somewhere else
405 I: Cancel and ignore future crashes of this program version
406 C: Cancel
407-Please choose (R/I/C):
408-</screen>
409-
410- <para>
411- Selecting <emphasis>Report Problem</emphasis> will walk you through
412- similar steps as when using ubuntu-bug. One important difference
413- is that a crash report will be marked as private when filed on
414- Launchpad, meaning that it will be visible to only a limited set
415- of bug triagers. These triagers will review the gathered data for private
416- information before making the bug report publicly visible.
417- </para>
418+Please choose (S/V/K/I/C): <userinput>s</userinput>
419+</screen>
420+
421+ <para>
422+ If you send the report, as was done above, the prompt will be returned immediately and the
423+ <filename>/var/crash</filename> directory will then contain 2 extra files:
424+ </para>
425+
426+<screen>
427+-rw-r----- 1 peter whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
428+-rw-rw-r-- 1 peter whoopsie 0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.upload
429+-rw------- 1 whoopsie whoopsie 0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.uploaded
430+</screen>
431+
432+ <para>
433+ Sending in a crash report like this will not immediately result in the creation of a new public bug.
434+ The report will be made private on Launchpad, meaning that it will be visible to only a limited set
435+ of bug triagers. These triagers will then scan the report for possible private data before creating a public bug.
436+ </para>
437
438 <!-- Include a bit here on using apport-retrace for generating a
439 full stack trace locally, for situations when the application
440@@ -301,18 +251,20 @@
441 <sect2 id="reporting-bugs-resources" status="review">
442 <title>Resources</title>
443 <itemizedlist>
444+
445 <listitem>
446 <para>
447- See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting
448- Bugs</ulink> Ubuntu wiki page.
449+ See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting Bugs</ulink> Ubuntu wiki page.
450 </para>
451 </listitem>
452+
453 <listitem>
454 <para>
455- Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information. Though some
456+ Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information. Though some
457 of it pertains to using a GUI.
458 </para>
459 </listitem>
460+
461 </itemizedlist>
462 </sect2>
463 </sect1>

Subscribers

People subscribed via source and target branches