1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
|
:B~ Reporting bugs
1~bugs Reporting bugs
Live systems are far from being perfect, but we want to make it as close as
possible to perfect - with your help. Do not hesitate to report a bug. It is
better to fill a report twice than never. However, this chapter includes
recommendations on how to file good bug reports.
For the impatient:
_* Always check first the image status updates on our homepage at
http://live-systems.org/ for known issues.
_* Before submitting a bug report always try to reproduce the bug with the
*{most recent versions}* of the branch of live-build, live-boot, live-config
and live-tools that you're using (like the newest 4.x version of live-build
if you're using live-build 4).
_* Try to give *{as specific information as possible}* about the bug. This
includes (at least) the version of live-build, live-boot, live-config, and
live-tools used and the distribution of the live system you are building.
2~ Known issues
Since Debian *{testing}* and Debian *{unstable}* distributions are moving
targets, when you specify either of them as the target system distribution,
a successful build may not always be possible.
% FIXME:
If this causes too much difficulty for you, do not build a system based on
*{testing}* or *{unstable}*, but rather, use *{stable}*. live-build always
defaults to the *{stable}* release.
Currently known issues are listed under the section 'status' on our homepage
at http://live-systems.org/.
It is out of the scope of this manual to train you to correctly identify and
fix problems in packages of the development distributions, however, there
are two things you can always try: If a build fails when the target
distribution is *{testing}*, try *{unstable}*. If *{unstable}* does not work
either, revert to *{testing}* and pin the newer version of the failing
package from *{unstable}* (see {APT pinning}#apt-pinning for details).
2~ Rebuild from scratch
To ensure that a particular bug is not caused by an uncleanly built system,
please always rebuild the whole live system from scratch to see if the bug
is reproducible.
2~ Use up-to-date packages
Using outdated packages can cause significant problems when trying to
reproduce (and ultimately fix) your problem. Make sure your build system is
up-to-date and any packages included in your image are up-to-date as well.
2~collect-information Collect information
Please provide enough information with your report. Include, at least, the
exact version of live-build where the bug is encountered and the steps to
reproduce it. Please use your common sense and provide any other relevant
information if you think that it might help in solving the problem.
To make the most out of your bug report, we require at least the following
information:
_* Architecture of the host system
_* Distribution of the host system
_* Version of live-build on the host system
_* Version of /{debootstrap}/ on the host system
_* Architecture of the live system
_* Distribution of the live system
_* Version of live-boot on the live system
_* Version of live-config on the live system
_* Version of live-tools on the live system
You can generate a log of the build process by using the #{tee}# command. We
recommend doing this automatically with an #{auto/build}# script (see
{Managing a configuration}#managing-a-configuration for details).
code{
# lb build 2>&1 | tee build.log
}code
At boot time, live-boot and live-config store their logfiles in
#{/var/log/live/}#. Check them for error messages.
Additionally, to rule out other errors, it is always a good idea to tar up
your #{config/}# directory and upload it somewhere (do *{not}* send it as an
attachment to the mailing list), so that we can try to reproduce the errors
you encountered. If this is difficult (e.g. due to size) you can use the
output of #{lb config --dump}# which produces a summary of your config tree
(i.e. lists files in subdirectories of #{config/}# but does not include
them).
Remember to send in any logs that were produced with English locale
settings, e.g. run your live-build commands with a leading #{LC_ALL=C}# or
#{LC_ALL=en_US}#.
2~ Isolate the failing case if possible
If possible, isolate the failing case to the smallest possible change that
breaks. It is not always easy to do this so if you cannot manage it for your
report, do not worry. However, if you plan your development cycle well,
using small enough change sets per iteration, you may be able to isolate the
problem by constructing a simpler 'base' configuration that closely matches
your actual configuration plus just the broken change set added to it. If
you have a hard time sorting out which of your changes broke, it may be that
you are including too much in each change set and should develop in smaller
increments.
2~ Use the correct package to report the bug against
If you do not know what component is responsible for the bug or if the bug
is a general bug concerning live systems, you can fill a bug against the
debian-live pseudo-package.
However, we would appreciate it if you try to narrow it down according to
where the bug appears.
3~ At build time while bootstrapping
live-build first bootstraps a basic Debian system with /{debootstrap}/. If a
bug appears here, check if the error is related to a specific Debian package
(most likely), or if it is related to the bootstrapping tool itself.
In both cases, this is not a bug in the live system, but rather in Debian
itself and probably we cannot fix it directly. Please report such a bug
against the bootstrapping tool or the failing package.
3~ At build time while installing packages
live-build installs additional packages from the Debian archive and
depending on the Debian distribution used and the daily archive state, it
can fail. If a bug appears here, check if the error is also reproducible on
a normal system.
If this is the case, this is not a bug in the live system, but rather in
Debian - please report it against the failing package. Running
/{debootstrap}/ separately from the Live system build or running #{lb
bootstrap --debug}# will give you more information.
Also, if you are using a local mirror and/or any sort of proxy and you are
experiencing a problem, please always reproduce it first by bootstrapping
from an official mirror.
3~ At boot time
If your image does not boot, please report it to the mailing list together
with the information requested in {Collect
information}#collect-information. Do not forget to mention, how/when the
image failed exactly, whether using virtualization or real hardware. If you
are using a virtualization technology of any kind, please always run it on
real hardware before reporting a bug. Providing a screenshot of the failure
is also very helpful.
3~ At run time
If a package was successfully installed, but fails while actually running
the Live system, this is probably a bug in the live system. However:
2~ Do the research
Before filing the bug, please search the web for the particular error
message or symptom you are getting. As it is highly unlikely that you are
the only person experiencing a particular problem. There is always a chance
that it has been discussed elsewhere and a possible solution, patch, or
workaround has been proposed.
You should pay particular attention to the live systems mailing list, as
well as the homepage, as these are likely to contain the most up-to-date
information. If such information exists, always include the references to it
in your bug report.
In addition, you should check the current bug lists for live-build,
live-boot, live-config and live-tools to see whether something similar has
already been reported.
2~ Where to report bugs
The ${project} keeps track of all bugs in the Bug Tracking System (BTS). For
information on how to use the system, please see
https://bugs.debian.org/. You can also submit the bugs by using the
#{reportbug}# command from the package with the same name.
In general, you should report build time errors against the live-build
package, boot time errors against live-boot, and run time errors against
live-config. If you are unsure of which package is appropriate or need more
help before submitting a bug report, please report it against the
debian-live pseudo-package. We will then take care about it and reassign it
where appropriate.
Please note that bugs found in distributions derived from Debian (such as
Ubuntu and others) should *{not}* be reported to the Debian BTS unless they
can be also reproduced on a Debian system using official Debian packages.
|
