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
=== modified file 'serverguide/C/reporting-bugs.xml'
--- serverguide/C/reporting-bugs.xml 2013-03-23 22:09:27 +0000
+++ serverguide/C/reporting-bugs.xml 2014-07-18 20:40:54 +0000
@@ -14,74 +14,57 @@
14 <title>Reporting Bugs in Ubuntu Server Edition</title>14 <title>Reporting Bugs in Ubuntu Server Edition</title>
1515
16 <para>16 <para>
17 While the Ubuntu Project attempts to release software with as few17 The Ubuntu Project, and thus Ubuntu Server, uses <ulink url="https://launchpad.net/">Launchpad</ulink>
18 bugs as possible, they do occur. You can help fix these bugs by18 as its bugtracker. In order to file a bug, you will need a Launchpad account. <ulink url="https://help.launchpad.net/YourAccount/NewAccount">Create
19 reporting ones that you find to the project. The Ubuntu Project19 one here</ulink> if necessary.
20 uses <ulink url="https://launchpad.net/">Launchpad</ulink>
21 to track its bug reports. In order to file a bug
22 about Ubuntu Server on Launchpad, you will need to
23 <ulink url="https://help.launchpad.net/YourAccount/NewAccount">create
24 an account</ulink>.
25 </para>20 </para>
2621
27 <sect2 id="reporting-bugs-ubuntu-bug" status="review">22 <sect2 id="reporting-bugs-apport-cli" status="review">
28 <title>Reporting Bugs With ubuntu-bug</title>23 <title>Reporting Bugs With apport-cli</title>
2924
30 <para>25 <para>
31 The preferred way to report a bug is with the26 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
32 <application>ubuntu-bug</application> command. The ubuntu-bug27 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
33 tool gathers information about the system useful to developers in28 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
34 diagnosing the reported problem that will then be included in the29 not have Internet access. The steps to take in these situations are described below.
35 bug report filed on Launchpad. Bug reports in Ubuntu need to be30 </para>
36 filed against a specific software package, thus the name of the31
37 package that the bug occurs in needs to be given to ubuntu-bug:32 <note>
38 </para>33 <para>
3934 The commands <application>apport-cli</application> and <application>ubuntu-bug</application> should give the same results on a CLI server.
40<screen>35 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
41<command>ubuntu-bug PACKAGENAME</command>36 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.
42</screen>37 </para>
4338 </note>
44 <para>39
45 For example, to file a bug against the openssh-server package, you would do:40 <para>
46 </para>41 Bug reports in Ubuntu need to be filed against a specific software package, so the name of the
4742 package (source package or program name/path) affected by the bug needs to be supplied to apport-cli:
48<screen>43 </para>
49<command>ubuntu-bug openssh-server</command>44
50</screen>45<screen>
5146<command>apport-cli PACKAGENAME</command>
52 <para>
53 You can specify either a binary package or the source package
54 for ubuntu-bug. Again using openssh-server as an example,
55 you could also generate the report against the source package
56 for openssh-server, openssh:
57 </para>
58
59<screen>
60<command>ubuntu-bug openssh</command>
61</screen>47</screen>
6248
63 <note>49 <note>
64 <para>50 <para>
65 See <xref linkend="package-management"/>51 See <xref linkend="package-management"/> for more information about packages in Ubuntu.
66 for more information about packages in Ubuntu.
67 </para>52 </para>
68 </note>53 </note>
6954
70 <para>55 <para>
71 The ubuntu-bug command will gather information about the system in56 Once apport-cli has finished gathering information you will be asked what to do with it. For
72 question, possibly including information specific to the specified57 instance, to report a bug in vim:
73 package, and then ask you what you would like to do with collected
74 information:
75 </para>58 </para>
7659
77<screen>60<screen>
78<command>ubuntu-bug postgresql</command>61<command>apport-cli vim</command>
7962
80*** Collecting problem information63*** Collecting problem information
8164
82The collected information can be sent to the developers to improve the65The collected information can be sent to the developers to improve the
83application. This might take a few minutes.66application. This might take a few minutes.
84..........67...
8568
86*** Send problem report to the developers?69*** Send problem report to the developers?
8770
@@ -89,117 +72,115 @@
89automatically opened web browser.72automatically opened web browser.
9073
91What would you like to do? Your options are:74What would you like to do? Your options are:
92 S: Send report (1.7 KiB)75 S: Send report (2.8 KB)
93 V: View report76 V: View report
94 K: Keep report file for sending later or copying to somewhere else77 K: Keep report file for sending later or copying to somewhere else
78 I: Cancel and ignore future crashes of this program version
95 C: Cancel79 C: Cancel
96Please choose (S/V/K/C):80Please choose (S/V/K/I/C):
97</screen>81</screen>
9882
99 <para>83 <para>
100 The options available are:84 The first three options are described below:
101 </para>85 </para>
10286
103 <para>87 <para>
104 <itemizedlist>88 <itemizedlist>
105 <listitem>89 <listitem>
106 <para><emphasis role="bold">Send Report</emphasis> Selecting90 <para><emphasis role="bold">Send:</emphasis>
107 Send Report submits the collected information to Launchpad as91 submits the collected information to Launchpad as part of the process
108 part of the process of filing a bug report. You will be92 of filing a new bug report. You will be given the opportunity to describe
109 given the opportunity to describe the situation that led up to93 the bug in your own words.
110 the occurrence of the bug.
111 </para>94 </para>
11295
113<screen>96<screen>
97
114*** Uploading problem information98*** Uploading problem information
11599
116The collected information is being sent to the bug tracking system.100The collected information is being sent to the bug tracking system.
117This might take a few minutes.101This might take a few minutes.
11891%10294%
119103
120*** To continue, you must visit the following URL:104*** To continue, you must visit the following URL:
121105
122https://bugs.launchpad.net/ubuntu/+source/postgresql-8.4/+filebug/kc6eSnTLnLxF8u0t3e56EukFeqJ?106 https://bugs.launchpad.net/ubuntu/+source/vim/+filebug/09b2495a-e2ab-11e3-879b-68b5996a96c8?
123107
124You can launch a browser now, or copy this URL into a browser on another108You can launch a browser now, or copy this URL into a browser on another computer.
125computer.109
126110
127Choices:111Choices:
128 1: Launch a browser now112 1: Launch a browser now
129 C: Cancel113 C: Cancel
130Please choose (1/C):114Please choose (1/C): <userinput>1</userinput>
131</screen>115</screen>
132116
133 <para>117 <para>
134 If you choose to start a browser, by default the text based web118 The browser that will be used when choosing '1' will be the one known on the system as
135 browser <application>w3m</application> will be used to finish filing119 <application>www-browser</application> via the
136 the bug report. Alternately, you can copy the given URL to a120 <ulink url="http://manpages.ubuntu.com/manpages/en/man8/update-alternatives.8.html">
137 currently running web browser.121 Debian alternatives system</ulink>. Examples of text-based browsers to install include <application>links</application>,
138 </para>122 <application>elinks</application>, <application>lynx</application>, and <application>w3m</application>.
139 </listitem>123 You can also manually point an existing browser at the given URL.
140124 </para>
141 <listitem>125 </listitem>
142 <para>126
143 <emphasis role="bold">View Report</emphasis> Selecting View127 <listitem>
144 Report causes the collected information to be displayed to128 <para>
145 the terminal for review.129 <emphasis role="bold">View:</emphasis>
146 </para>130 displays the collected information on the screen for review. This can
147131 be a lot of information. Press 'Enter' to scroll by screenful. Press 'q'
148<screen>132 to quit and return to the choice menu.
149Package: postgresql 8.4.2-2133 </para>
150PackageArchitecture: all134 </listitem>
151Tags: lucid135
152ProblemType: Bug136 <listitem>
153ProcEnviron:137 <para>
154 LANG=en_US.UTF-8138 <emphasis role="bold">Keep:</emphasis>
155 SHELL=/bin/bash139 writes the collected information to disk. The resulting file can be later used to
156Uname: Linux 2.6.32-16-server x86_64140 file the bug report, typically after transferring it to another Ubuntu system.
157Dependencies:
158 adduser 3.112ubuntu1
159 base-files 5.0.0ubuntu10
160 base-passwd 3.5.22
161 coreutils 7.4-2ubuntu2
162...
163</screen>
164
165 <para>
166 After viewing the report, you will be brought back to the same
167 menu asking what you would like to do with the report.
168 </para>
169 </listitem>
170
171 <listitem>
172 <para>
173 <emphasis role="bold">Keep Report File</emphasis> Selecting Keep
174 Report File causes the gathered information to be written to
175 a file. This file can then be used to later file a bug report
176 or transferred to a different Ubuntu system for reporting.
177 To submit the report file, simply give it as an argument to
178 the ubuntu-bug command:
179 </para>141 </para>
180142
181<screen>143<screen>
182What would you like to do? Your options are:144What would you like to do? Your options are:
183 S: Send report (1.7 KiB)145 S: Send report (2.8 KB)
184 V: View report146 V: View report
185 K: Keep report file for sending later or copying to somewhere else147 K: Keep report file for sending later or copying to somewhere else
148 I: Cancel and ignore future crashes of this program version
186 C: Cancel149 C: Cancel
187Please choose (S/V/K/C): <userinput>k</userinput>150Please choose (S/V/K/I/C): <userinput>k</userinput>
188Problem report file: /tmp/apport.postgresql.v4MQas.apport151Problem report file: /tmp/apport.vim.1pg92p02.apport
189152</screen>
190<command>ubuntu-bug /tmp/apport.postgresql.v4MQas.apport</command>153
191154 <para>
192*** Send problem report to the developers?155 To report the bug, get the file onto an internet-enabled Ubuntu system and apply apport-cli
193...156 to it. This will cause the menu to appear immediately (the information is already collected).
194</screen>157 You should then press 's' to send:
195 </listitem>158 </para>
196159
197 <listitem>160<screen>
198 <para>161<command>apport-cli apport.vim.1pg92p02.apport</command>
199 <emphasis role="bold">Cancel</emphasis> Selecting162</screen>
200 Cancel causes the collected information to be discarded.163
201 </para>164<para>
202 </listitem>165To directly save a report to disk (without menus) you can do:
166
167<screen>
168<command>apport-cli vim --save apport.vim.test.apport</command>
169</screen>
170
171Report names should end in <emphasis>.apport</emphasis> .
172</para>
173
174 <note>
175 <para>
176 If this internet-enabled system is non-Ubuntu/Debian, apport-cli is not available so the
177 bug will need to be created manually. An apport report is also not to be included as an
178 attachment to a bug either so it is completely useless in this scenario.
179 </para>
180 </note>
181
182 </listitem>
183
203 </itemizedlist>184 </itemizedlist>
204 </para>185 </para>
205 </sect2>186 </sect2>
@@ -207,89 +188,58 @@
207 <sect2 id="apport-crash-catching" status="review">188 <sect2 id="apport-crash-catching" status="review">
208 <title>Reporting Application Crashes</title>189 <title>Reporting Application Crashes</title>
209190
210 <para>191 <para>
211 The software package that provides the ubuntu-bug utility, 192 The software package that provides the apport-cli utility, <application>apport</application>,
212 <application>apport</application>, can be configured to trigger193 can be configured to automatically capture the state of a crashed application. This
213 when applications crash. This is disabled by default, as capturing194 is enabled by default (in <filename>/etc/default/apport</filename>).
214 a crash can be resource intensive depending on how much memory195 </para>
215 the application that crashed was using as apport captures and196
216 processes the core dump.197 <para>
217 </para>198 After an application crashes, if enabled, apport will store a crash report under <filename>/var/crash</filename>:
218199 </para>
219 <para>200
220 Configuring apport to capture information about201<screen>
221 crashing applications requires a couple of steps. First,202-rw-r----- 1 peter whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
222 <application>gdb</application> needs to be installed; it is not203</screen>
223 installed by default in Ubuntu Server Edition.204
224 </para>205 <para>
225206 Use the <application>apport-cli</application> command without arguments to process any pending crash reports. It
226<screen>207 will offer to report them one by one.
227<command>sudo apt-get install gdb</command>208 </para>
228</screen>
229
230 <para>
231 See <xref linkend="package-management"/>
232 for more information about managing packages in Ubuntu.
233 </para>
234
235 <para>
236 Once you have ensured that gdb is installed, open the file
237 <filename>/etc/default/apport</filename> in your text editor,
238 and change the <emphasis>enabled</emphasis> setting to be
239 <emphasis role="bold">1</emphasis> like so:
240 </para>
241
242<programlisting>
243# set this to 0 to disable apport, or to 1 to enable it
244# you can temporarily override this with
245# sudo service apport start force_start=1
246enabled=<userinput>1</userinput>
247
248# set maximum core dump file size (default: 209715200 bytes == 200 MB)
249maxsize=209715200
250</programlisting>
251
252 <para>
253 Once you have completed editing
254 <filename>/etc/default/apport</filename>,
255 start the apport service:
256 </para>
257
258<screen>
259<command>sudo start apport</command>
260</screen>
261
262 <para>
263 After an application crashes, use the
264 <application>apport-cli</application> command to search for the
265 existing saved crash report information:
266 </para>
267209
268<screen>210<screen>
269<command>apport-cli</command>211<command>apport-cli</command>
270212
271*** dash closed unexpectedly on 2010-03-11 at 21:40:59.213*** Send problem report to the developers?
272214
273If you were not doing anything confidential (entering passwords or other215After the problem report has been sent, please fill out the form in the
274private information), you can help to improve the application by216automatically opened web browser.
275reporting
276the problem.
277217
278What would you like to do? Your options are:218What would you like to do? Your options are:
279 R: Report Problem...219 S: Send report (153.0 KB)
220 V: View report
221 K: Keep report file for sending later or copying to somewhere else
280 I: Cancel and ignore future crashes of this program version222 I: Cancel and ignore future crashes of this program version
281 C: Cancel223 C: Cancel
282Please choose (R/I/C):224Please choose (S/V/K/I/C): <userinput>s</userinput>
283</screen>225</screen>
284226
285 <para>227 <para>
286 Selecting <emphasis>Report Problem</emphasis> will walk you through228 If you send the report, as was done above, the prompt will be returned immediately and the
287 similar steps as when using ubuntu-bug. One important difference229 <filename>/var/crash</filename> directory will then contain 2 extra files:
288 is that a crash report will be marked as private when filed on230 </para>
289 Launchpad, meaning that it will be visible to only a limited set231
290 of bug triagers. These triagers will review the gathered data for private232<screen>
291 information before making the bug report publicly visible.233-rw-r----- 1 peter whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
292 </para>234-rw-rw-r-- 1 peter whoopsie 0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.upload
235-rw------- 1 whoopsie whoopsie 0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.uploaded
236</screen>
237
238 <para>
239 Sending in a crash report like this will not immediately result in the creation of a new public bug.
240 The report will be made private on Launchpad, meaning that it will be visible to only a limited set
241 of bug triagers. These triagers will then scan the report for possible private data before creating a public bug.
242 </para>
293243
294 <!-- Include a bit here on using apport-retrace for generating a244 <!-- Include a bit here on using apport-retrace for generating a
295 full stack trace locally, for situations when the application245 full stack trace locally, for situations when the application
@@ -301,18 +251,20 @@
301 <sect2 id="reporting-bugs-resources" status="review">251 <sect2 id="reporting-bugs-resources" status="review">
302 <title>Resources</title>252 <title>Resources</title>
303 <itemizedlist>253 <itemizedlist>
254
304 <listitem>255 <listitem>
305 <para>256 <para>
306 See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting257 See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting Bugs</ulink> Ubuntu wiki page.
307 Bugs</ulink> Ubuntu wiki page.
308 </para>258 </para>
309 </listitem>259 </listitem>
260
310 <listitem>261 <listitem>
311 <para>262 <para>
312 Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information. Though some263 Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information. Though some
313 of it pertains to using a GUI.264 of it pertains to using a GUI.
314 </para>265 </para>
315 </listitem>266 </listitem>
267
316 </itemizedlist>268 </itemizedlist>
317 </sect2>269 </sect2>
318 </sect1>270 </sect1>

Subscribers

People subscribed via source and target branches