How to debug installation problems

Effective anaconda bug reporting

anaconda is a complex program that runs in a minimal environment. It uses a lot of software components to get its job done. It exercises the computer's hardware pretty thoroughly. It's very closely tied to a particular product build, and it's changed quite frequently. This makes it tough to develop and debug. It also makes bug reporting difficult.

This document will help you write more effective bug reports for anaconda. It will teach you what information to extract from your system that will help us debug your problem. It will also teach you which things are not anaconda bugs and should be reported elsewhere.

Narrowing it down to a release

Before you do anything else, please try to figure out if your bug is against the latest version of your software product. If you're running into a bug on FC6 but we're working on Fedora 8, that's not very helpful. It may even be fixed already. Please try the latest release available. If you're testing the development tree, please check against the latest nightly build available. Of course, anaconda doesn't get rebuilt every day so it may be worth your time to check the build report and see if there's a newer anaconda before you try another nightly tree.

Still a bug? That's too bad, but alright. Please remember the version of Fedora or RHEL that you found a bug in. If you're testing the development tree, it is especially important that you remember the exact day the tree came from. You'll find out why in a minute.

There's two pieces of version information that are important. First is the anaconda version number. This is pretty easy to figure out - anaconda prints it out when it's starting up. If you look quickly, you'll see a message like this:

Greetings.
anaconda installer init version 11.1.0.47 starting

That's the anaconda version number. The second is the tree version. If you're using an official release, just remember that. If you're using the development tree, things are a little more tricky. You can check and see if the installation source has a date in the path. If so, that's probably the version information. Otherwise, look in the installation source for a .treeinfo file. That has a timestamp and version that will help us figure out which tree you were using.

Identifying your type of bug

Next, it's useful to figure out what type of bug you are seeing. The biggest major bug types here are: bugs in the loader, bugs in the second stage, bugs in the kernel, bugs in your hardware or its drivers, and bugs in X. It's pretty easy to tell which is which once you know what to look for.

File:Anaconda BugReporting loader-stacktrace.png

If your bug looks like this, congratulations. You have found a bug in the first stage of anaconda. We call this the loader. It's written in C, and what you are seeing in front of you is a dump of the hex addresses of functions. This doesn't mean anything to you, but it tells us exactly where the bug is occurring and how we got there. You'll need to copy those numbers down exactly as you see them. Taking a picture of the screen is a common way to get these numbers.

Unfortunately, these numbers change every time anaconda or one of the components it depends upon is rebuilt. That's because the locations of functions in the compiled program change. If you don't remember the exact version of the tree you're using, we won't be able to match those numbers up to the correct function names and we'll just ask you to try again with a later tree.

File:Anaconda BugReporting stage2-backtrace.png

If your bug looks like this, congratulations. You have found a bug in the second stage of anaconda. This is a little bit less disasterous and much easier to debug. What you're seeing in front of you is actually quite similar to a loader stack trace, but way more informative. You're seeing an exception report from Python.

You will have a very extensive file written out with tons of useful debugging information. You'll also have the opportunity to save that file to a floppy or a remote host (depending on if you have a floppy drive or network connection), debug the problem, or reboot. You probably don't want to debug it, and you certainly don't want to reboot just yet. The point here is, we'll need this very large file. Don't assume that just the small shown blurb is the full debugging output, or we'll have to ask you for the rest later.

If your install has just suddenly stopped doing anything, you may have encountered a bug in the kernel or a hardware driver. Try to press ctrl-alt-F4. This should take you over to the fourth virtual console unless things are seriously screwed up. If you see something like the above, you have found a kernel bug. This is not a problem with anaconda. We still want your bug report, but it should be filed against the kernel component. They'll want a picture of what you see on the screen, and perhaps more. That's outside the scope of this document. In fact, you can just quit reading this now.

What information do we need?

Now that we've identified the kind of error you see, we can figure out what sort of useful information you should include in your bug report. Here's the basic information that all bug reports should include:

• The traceback information explained earlier - either a picture of the loader stack trace, or the complete python exception report.
• A brief outline of your hardware, if this seems like a hardware-related problem. We may need more complete information later, in which case we'll give you specific commands to run. If you have a pre-built computer (like one you bought from Dell, Apple, or other manufacturers) we're not interested in the model so much as the components. What sorts of disks do you have? What's the video card? Those details are more important
• The version of anaconda that crashed, or at least the specific tree you're installing from. The tree version is always useful.

Were you doing a kickstart install? Please also include:

• Your complete kickstart file. You can remove or obscure sensitive information like passwords, but please otherwise include the full thing.

Were you partitioning your disks? Please also include:

• What sort of partitioning scheme you were trying to set up, and what kinds of filesystems you wanted to make.
• Are USB or Firewire devices attached?
• Were you using any advanced storage mechanisms (RAID-on-LVM, iSCSI, multipath, etc.)?
• What you had on your disk(s) to begin with. If you put together a machine from disks you just had laying around, please remember there may be something on them from a previous installation that you don't even remember. This is more common than you may think.
• If you have any other operating systems installed, and what partitions they might be using.

Were you setting up networking? Please also include:

• What sort of networking hardware you have.
• What you were trying to do.

Writing the bug report

Finally, the moment we've all been waiting for - writing up the bug report. Writing a useful one isn't as easy as you might think, however, so here are some pointers for getting it done.

• Version: Unless you are using a particular release, please use the devel version. Test releases should be filed under the devel version as well.
• Component: This is usually anaconda, but it might also be something like parted, pykickstart, or mkinitrd. Just set it to anaconda and we'll move it if we need to.
• Summary: Please write a descriptive summary that includes at least a couple useful keywords. Don't make it overly long, because that's what the description is for. But please remember that we have lots of bugs and look at them in big long lists, so a useful summary will help your bug to be noticed. Things like "Installed crashed" or "Bad: anaconda hung" are not useful. Something like "Clicking Back button on confirm screen hangs" is much more descriptive.
• Description: If you're not going to use the template, please just delete it. Let us know what you were doing when the error happened. What steps did you take to cause it? Anything else seem relevant to you? Attach all the information we outlined for you earlier. If you've got a stack trace or the brief exception message (just the first part of the giant exception file), include that in the description since it makes for faster searching.
• Attachments: Giant files should be attachments. Putting them in comments in the bug report makes it hard to follow.
• Other fields: You shouldn't usually need to touch any of the other fields. We don't work with priority and severity very much. The security-response-team should never be added to the CC list, since anaconda is special and falls outside the realm of typical security problems.
• Finally: Please, don't rant in your description. We know it's frustrating for the installer to fail in the middle of what you want to do. And we know there's plenty of bugs. However, yelling at someone you're also asking to do something for you doesn't put your bug at the top of the priority list. Just be considerate.

What now?

Now, we'll look at your bug report. It may take us a while to get to your bug, or it may happen very quickly. We may ask you for more information, to try running a command, or to try an update. In general, it's helpful if your computer is still available for testing. If you discover a bug in anaconda, report it, and then immediately install something else so that we can't try things out, your bug will most likely not get fixed.

Also, please do report your bugs. If you're afraid of reporting it because you think it's a duplicate, file it anyway. We can always handle duplicates. Please don't assume that we know about your particular bug unless you report it. If you don't report it, it may never get fixed.