| 1 |
Dealing with d-i installation reports
|
| 2 |
=====================================
|
| 3 |
|
| 4 |
Debian-Installer has a large number of installation reports in the BTS.
|
| 5 |
These are very valuable to us, since they're our only way of knowing how
|
| 6 |
well d-i is doing on widely varied hardware, operated by users who are not
|
| 7 |
intimatly familiar with d-i. But after each beta release of the installer,
|
| 8 |
we get more installation reports than our limited manpower can easily deal
|
| 9 |
with.
|
| 10 |
|
| 11 |
This document is aimed at getting a Debian developer who is not
|
| 12 |
familiar with d-i up to the point where you can help us process and
|
| 13 |
categorise our install reports. Along the way, you should learn a lot more
|
| 14 |
about d-i.
|
| 15 |
|
| 16 |
It would be a good idea to go check out our web site
|
| 17 |
(http://www.debian.org/devel/debian-installer), read the
|
| 18 |
INSTALLATION-HOWTO, and do a test install to a spare swap partition or
|
| 19 |
machine, to get a feel for what d-i looks like, and what a user sees before
|
| 20 |
filing an installation report. You might want to file your own installation
|
| 21 |
report summarising your experiences, too.
|
| 22 |
|
| 23 |
|
| 24 |
The BTS
|
| 25 |
-------
|
| 26 |
|
| 27 |
All of our install reports should be under the "installation-reports"
|
| 28 |
pseudo-package in the BTS, although sometimes they are miscategorised in
|
| 29 |
other places (like under "installation"). As with any report, the users
|
| 30 |
often get the severity wrong; just because d-i breaks on their machine does
|
| 31 |
not really warrent a grave severity installation report.
|
| 32 |
|
| 33 |
The more current, interesting, and easier to deal with reports are at the
|
| 34 |
end of the list of normal severity reports. As you head back in time to the
|
| 35 |
beginning of the list, the versions of the installer become progressively
|
| 36 |
more broken, and our memories of the old bugs fainter.
|
| 37 |
|
| 38 |
The process of categorising an installation report is mainly one of reading
|
| 39 |
over the report, and identifying problems, and working out what part of the
|
| 40 |
installer is responsible for the problem, and cloning off a bug report to
|
| 41 |
be reassigned to that installer component. The goal is to make sure the
|
| 42 |
right people see the report, and make sure that no useful information is
|
| 43 |
disregarded or lost.
|
| 44 |
|
| 45 |
|
| 46 |
Processing a sample report
|
| 47 |
--------------------------
|
| 48 |
|
| 49 |
Let's look at a sample installation report, bug #230396. This walkthrough
|
| 50 |
is provided as an example of how someone knowledgeable about the parts of
|
| 51 |
d-i and how they interact would process this report. Later sections of this
|
| 52 |
document will try to fill in the gaps you'll need to be able to do the
|
| 53 |
same.
|
| 54 |
|
| 55 |
The first thing to take note of is the version of the installer, and the
|
| 56 |
media used to install and basic description of the machine. Without this
|
| 57 |
info, many install reports will be useless, so if you find an install
|
| 58 |
report without that basic info, or that is too vague about it, you may need
|
| 59 |
to write the reporter to get more info, and tag it moreinfo in the
|
| 60 |
meantime.
|
| 61 |
|
| 62 |
The summary of it is a little way down:
|
| 63 |
|
| 64 |
Base System Installation Checklist:
|
| 65 |
|
| 66 |
Initial boot worked: [O]
|
| 67 |
Configure network HW: [E]
|
| 68 |
Config network: [O]
|
| 69 |
Detect CD: [ ]
|
| 70 |
Load installer modules: [E]
|
| 71 |
Detect hard drives: [ ]
|
| 72 |
Partition hard drives: [ ]
|
| 73 |
Create file systems: [ ]
|
| 74 |
Mount partitions: [ ]
|
| 75 |
Install base system: [ ]
|
| 76 |
Install boot loader: [ ]
|
| 77 |
Reboot: [ ]
|
| 78 |
[O] = OK, [E] = Error (please elaborate below), [ ] = didn't try it
|
| 79 |
|
| 80 |
Well this install didn't go very well, they had problems and failed to
|
| 81 |
install. Looking in the "Comments/Problems" section, we see:
|
| 82 |
|
| 83 |
I have a D-Link DE-220 ISA Card. The address/irq is 0x300, 11.
|
| 84 |
The detection failed (its not a PNP card).
|
| 85 |
Choosing the module 'ne' also failed, because it did not prompt me to
|
| 86 |
enter the io port and irq.
|
| 87 |
|
| 88 |
I was able to get the card to work by using insmod with the correct
|
| 89 |
io/irq from the command line.
|
| 90 |
|
| 91 |
That explains the first "E" in the list. The part of the installer that is
|
| 92 |
responsible for configuring network hardware is the ethdetect package. The
|
| 93 |
problem is that apparently it did not make it easy enough for this user to
|
| 94 |
manually congfigure his ISA ethernet card (it autodetects only PCI cards).
|
| 95 |
So, look up its bug list and see if it has a bug for this issue. It does
|
| 96 |
not, so let's give it one:
|
| 97 |
|
| 98 |
clone 230396 -1
|
| 99 |
reassign -1 ethdetect
|
| 100 |
retitle -1 failed to configure a D-Link DE-220 ISA Card
|
| 101 |
tags -1 d-i
|
| 102 |
|
| 103 |
See the BTS documentation for help with the clone command if you're not
|
| 104 |
familiar with it. Notice that the new bug is retitled, to include as much
|
| 105 |
information about the hardware that caused the problem as possible. And
|
| 106 |
a d-i tag is added. We use these tags to be able to find all bugs in d-i,
|
| 107 |
across the set of packages that compose it.
|
| 108 |
|
| 109 |
Moving on the the next "E", we find this in the report:
|
| 110 |
|
| 111 |
Load installer modules:
|
| 112 |
|
| 113 |
Some of the mirrors listed (I tried 2 in canada) don't have the
|
| 114 |
installer files. (At least thats whats returned in the error message)
|
| 115 |
|
| 116 |
While downloading files from the mirror, suddenly the installer quits to
|
| 117 |
a console screen with the message "Terminated" repeating over and again
|
| 118 |
once every few seconds.
|
| 119 |
|
| 120 |
The part of d-i that's responsible for picking a mirror to download debian
|
| 121 |
from is called "choose-mirror". It would be acceptible to reassign this
|
| 122 |
bug to it, as follows:
|
| 123 |
|
| 124 |
clone 230396 -2
|
| 125 |
reassign -2 choose-mirror
|
| 126 |
retitle -2 failed to load all installer modules from Canadian mirrors
|
| 127 |
tags -2 d-i
|
| 128 |
|
| 129 |
However, the second paragraph, about the installer crashing and repeating
|
| 130 |
an error message is really more interesting. This is a common symptom of
|
| 131 |
something going badly wrong, and if we look up at the top of the
|
| 132 |
installation report, where it describes the system, we find it has only 24
|
| 133 |
MB of memory. Note that beta 2 of d-i is documented to not work with less
|
| 134 |
than 32 MB. So the installer ran out of memory. Rather than discard the
|
| 135 |
report because of that, let's clone off a bug report, because it should
|
| 136 |
surely deal with low memory better than going into a crash loop:
|
| 137 |
|
| 138 |
clone 230396 -3
|
| 139 |
reassign -3 debian-installer
|
| 140 |
retitle -3 goes into crash loop loading installer with 24 MB of ram
|
| 141 |
tags -3 d-i
|
| 142 |
|
| 143 |
If it seems to be a general problem or it's not clear what part of the
|
| 144 |
installer is really at fault, it's acceptable to assign bugs to the
|
| 145 |
debian-installer pseudo package. The d-i team can always make better
|
| 146 |
reassignments later.
|
| 147 |
|
| 148 |
There is a bit more to this report that I left out. The user commented
|
| 149 |
that:
|
| 150 |
|
| 151 |
The root floppy has what I consider a vague name.
|
| 152 |
Also, the rawrite2.exe tool wouldn't read the image files from the hard
|
| 153 |
drive because the filename was too long. I had to rename and shorten
|
| 154 |
the image file names before I could create them under windows. Maybe
|
| 155 |
this is more of a problem with rawrite, but I digress.
|
| 156 |
|
| 157 |
This could also stand to be cloned off and reassigned to the
|
| 158 |
debian-installer pseudo package. It's a valuable observation.
|
| 159 |
|
| 160 |
clone 230396 -4
|
| 161 |
reassign -4 debian-installer
|
| 162 |
retitle -4 floppy images have bad names that play badly with rawrite2
|
| 163 |
tags -4 d-i
|
| 164 |
|
| 165 |
Finally, after sending off the four clone commands to
|
| 166 |
control@bugs.debian.org, you can close the installation report. Be sure to
|
| 167 |
thank the reporter for his report, suggest things he might try to get a
|
| 168 |
successfull install (upgrade his memory in this case..), and mention that
|
| 169 |
his issues have been brought to the attention of the debian-installer team.
|
| 170 |
You may also want to mail the maintainers of the packages that the report
|
| 171 |
was cloned to (if the packages are not part of d-i), to make sure they
|
| 172 |
notice the problem and understand it.
|
| 173 |
|
| 174 |
Note that some installation reports will only have one bug-worthy issue in
|
| 175 |
them. It's probably easier to not clone these, and just reassign the whole
|
| 176 |
installation report to the appropriatre package.
|
| 177 |
|
| 178 |
|
| 179 |
Background information
|
| 180 |
----------------------
|
| 181 |
|
| 182 |
The example above showed that you need to know a certain amount of
|
| 183 |
information about the internals of d-i to properly categorise installation
|
| 184 |
reports.
|
| 185 |
|
| 186 |
A good place to start is by reading the d-i TODO list, in d-i's CVS.
|
| 187 |
This command will check out the whole d-i tree, which will be useful in
|
| 188 |
other ways too:
|
| 189 |
|
| 190 |
cvs -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/d-i co debian-installer
|
| 191 |
|
| 192 |
Then look in doc/TODO to see some of our most pressing and largest
|
| 193 |
problems. More known problems with the beta releases are documented on the
|
| 194 |
errata page, <http://www.debian.org/devel/debian-installer/errata>. If you
|
| 195 |
become familiar with these well-known problems, you can save a lot of time
|
| 196 |
dealing with the parts of install reports that repeat them, and focus
|
| 197 |
on the more interesting stuff.
|
| 198 |
|
| 199 |
You should also be aware that after a successful install, d-i writes all of
|
| 200 |
its logs to /var/log/debian-installer/ on the installed system. These logs
|
| 201 |
can be very useful.
|
| 202 |
|
| 203 |
Let's go through the stages of the install, and see what parts of the
|
| 204 |
installer are responsible for them.
|
| 205 |
|
| 206 |
Initial boot worked: [ ]
|
| 207 |
|
| 208 |
The parts of the installer responsible for the inital boot include the
|
| 209 |
linux kernel (if the boot error looks like a kernel bug). Debian-Installer
|
| 210 |
uses the stock Debian kernel image, At the time of this writing, it is
|
| 211 |
taken from the kernel-image-2.4.24-1-386 package for i386.
|
| 212 |
|
| 213 |
After the kernel, it's most likely a bug in the installer's initrd. If it
|
| 214 |
gets to init, and does not get to a prompt for a language, that's a good
|
| 215 |
bet. Such bugs should be assigned to the debian-installer pseudo-package.
|
| 216 |
|
| 217 |
If they're booting from a CDROM, the bug could be in the debian-cd package,
|
| 218 |
or in isolinux.
|
| 219 |
|
| 220 |
If they're netbooting, the problem could be anywhere..
|
| 221 |
|
| 222 |
If booting from floppies, a likely candidate is a bad floppy.
|
| 223 |
|
| 224 |
If booting from a USB memory stick, the most common cause of failure to
|
| 225 |
boot at all is an old BIOS.
|
| 226 |
|
| 227 |
If it booted up past init, but never got around to interacting with the
|
| 228 |
user, then other candidates include problems in main-menu and cdebconf.
|
| 229 |
main-menu is what drives the whole installation, and cdebconf is of course
|
| 230 |
what is used for interation. If these fail, the install won't get far.
|
| 231 |
|
| 232 |
Also, before the next item in the checklist, the installer will prompt
|
| 233 |
the user for their language (via the languagechooser package), and keyboard
|
| 234 |
(via kbd-chooser).
|
| 235 |
|
| 236 |
Configure network HW: [ ]
|
| 237 |
|
| 238 |
The frontend for network hardware configuration is the ethdetect package.
|
| 239 |
It in turn calls hw-detect to scan for PCI and PCMCIA hardware. Don't worry
|
| 240 |
which to assign bugs to, as they have the same source package.
|
| 241 |
|
| 242 |
If the user has PCI hardware that is not detected, then the bug should be
|
| 243 |
assigned to the discover-data package, since hw-detect uses discover to do
|
| 244 |
its job. When assigning a bug to discover-data, be sure that it includes
|
| 245 |
the module that should be loaded, and the PCI ID that discover should
|
| 246 |
associate with this module.
|
| 247 |
|
| 248 |
If the user has hardware that is detected, but the module fails to load,
|
| 249 |
it could be a bug in the kernel, and if so should be reassigned to the
|
| 250 |
appropriate kernel package, such as kernel-image-2.4.24-1-386.
|
| 251 |
|
| 252 |
Similarly, hangs during hardware detection are often kernel bugs.
|
| 253 |
|
| 254 |
Config network: [ ]
|
| 255 |
|
| 256 |
This is taken care of by the netcfg package. Users sometimes put an E
|
| 257 |
here when it belonged in "Configure network HW" instead.
|
| 258 |
|
| 259 |
If the problem relates to entering IP address, gateway, netmask, hostname,
|
| 260 |
etc, then netcfg is the place to assign it.
|
| 261 |
|
| 262 |
Netcfg runs a DHCP client, and currently dhcp-client is the one used.
|
| 263 |
Problems in configuring DHCP can be reassigned to that package.
|
| 264 |
|
| 265 |
Detect CD: [ ]
|
| 266 |
|
| 267 |
This is done by cdrom-detect. Of course, the kernel has to be able to see
|
| 268 |
the CD drive, and the CD has to be a valid CD. discover also takes care of
|
| 269 |
probing for SCSI and IDE disks, so if the installer cannot find their CD
|
| 270 |
drive at all, that's a place to look too.
|
| 271 |
|
| 272 |
Load installer modules: [ ]
|
| 273 |
|
| 274 |
Depending on the type of install, the actual retrieval of the d-i udebs
|
| 275 |
will be done by one of cdrom-retriever, net-retriever, or floppy-retriever.
|
| 276 |
They are all controlled by anna (from the package by that name).
|
| 277 |
|
| 278 |
It's more likely that problems in this area have to do with bad media, or
|
| 279 |
networking issues, or bad mirrors.
|
| 280 |
|
| 281 |
Detect hard drives: [ ]
|
| 282 |
|
| 283 |
This is taken care of at the kernel level by discover again. If it fails to
|
| 284 |
find the drive, it's important to know what module should be loaded, and
|
| 285 |
of course the specifics of the hardware.
|
| 286 |
|
| 287 |
Partition hard drives: [ ]
|
| 288 |
|
| 289 |
d-i actually contains three different modules that can do this.
|
| 290 |
|
| 291 |
partman is our new system, which is now the default on most architectures.
|
| 292 |
It uses parted exclusively, and does file system creation too.
|
| 293 |
|
| 294 |
The old system is the "partitioner" module. This uses libparted to list the
|
| 295 |
existing partitions, and then cfdisk to do the actual partitioning.
|
| 296 |
|
| 297 |
If they say they used the automatic partitioner, that is "autopartkit".
|
| 298 |
It uses parted exclusively, and also takes care of file system creation in
|
| 299 |
the same step.
|
| 300 |
|
| 301 |
Create file systems: [ ]
|
| 302 |
Mount partitions: [ ]
|
| 303 |
|
| 304 |
Generally this is also partman's job. If the user used "partitioner" above,
|
| 305 |
then they will use partconf for these two steps. partconf uses libparted to
|
| 306 |
list the partitions. It uses standard mkfs.fstype programs to create the
|
| 307 |
various file systems.
|
| 308 |
|
| 309 |
Install base system: [ ]
|
| 310 |
|
| 311 |
This step is handled by base-installer, which uses debootstrap. If there is
|
| 312 |
a problem, it will 90% of the time be a problem with debootstrap, and the
|
| 313 |
debootstrap log file will be essential to working it out.
|
| 314 |
|
| 315 |
Install boot loader: [ ]
|
| 316 |
|
| 317 |
The default boot loader used to be lilo (for betas 1 and 2), and is now
|
| 318 |
grub (on i386 anyway). The various bootloader installation programs are
|
| 319 |
lilo-installer, grub-installer, yaboot-installer, and so on ad naseum.
|
| 320 |
|
| 321 |
If they had a boot loader install problem, it's important to know how their
|
| 322 |
partitions were set up.
|
| 323 |
|
| 324 |
Reboot: [ ]
|
| 325 |
|
| 326 |
d-i does some things between boot loader install and reboot, that might
|
| 327 |
cause an error here. The prebaseconfig package is responsible for that.
|
| 328 |
|
| 329 |
Most often, a user will put an E here if their installed system failed to
|
| 330 |
boot. The boot loader is a good possibility, and if so see above. Other
|
| 331 |
possibilities include a kernel problem, and problems in the debian base
|
| 332 |
system.
|
| 333 |
|
| 334 |
base-config also enters the picture here, as do tasksel, aptitude, all
|
| 335 |
the debian packages that could possibly be installed. If the user finds
|
| 336 |
problems in this part of the install, clone them off to the appropriate
|
| 337 |
debian package.
|
| 338 |
|
| 339 |
Various parts of d-i are responsible for setting up parts of the installed
|
| 340 |
system. Problems with /etc/network/interfaces, /etc/hosts, and similar are
|
| 341 |
in the purview of netcfg, while /etc/fstab is set up by partconf (or
|
| 342 |
autopartkit, or partman). hw-detect is responsible for ensuring that the
|
| 343 |
right modules are put in /etc/modules, and that packages like discover,
|
| 344 |
pcmcia-cs, and hotplug are installed onto the base system to deal with the
|
| 345 |
hardware.
|
| 346 |
|
| 347 |
|
| 348 |
More information
|
| 349 |
----------------
|
| 350 |
|
| 351 |
The above is only an overview, and if you need more detail on a part of the
|
| 352 |
installer, you should post to debian-boot@lists.debian.org, or ask on the
|
| 353 |
#debian-boot irc channel on irc.debian.org. Or see the source.
|
Parent Directory
| 
Revision Log