From Fedora Project Wiki

m (1 revision(s))
(review doc)
 
(24 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<!-- page was renamed from AnacondaBugReporting
<!-- page was renamed from AnacondaBugReporting
-->
-->
= 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.
== Narrowing it Down ==


This document will help you write more effective bug reports for anaconda. It will teach you what information to extract from your
Before doing anything else, please try to figure out if you're testing the latest version of anaconda - this goes for all software products. If you're running into a problem in F10 while we're developing F12, a bug report will not be very helpful and the problem may even be fixed already. If you ever encounter a bug that is not in the latest anaconda, please locate the newest one and try that.
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 ==
To check which version of anaconda you're running, you need only watch the screen when anaconda starts up. It will print something like


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.
<pre>
Greetings.
anaconda installer init version 11.5.0.47 starting
</pre>
 
And that's your version of anaconda!
 
The other useful number is the tree. If you're using an official release, all we need is which Fedora you're installing. If, on the other hand, you're using the development tree (Rawhide), there are two ways to discover which tree you're using. Often the installation source will have a date in the path, which will tell us which build to look at. If your install source does not have a date, its .treeinfo file should contain a timestamp and a version number.


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.
If you cannot remember what you were using when you encountered the bug, please try again with the newest one. If you don't, we're just going to have to ask you to do so and it would save everyone time not to deal with that.


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:
If you are unwilling to try the newest rawhide to see if the bug is still present, especially if the rawhide you were using is an old one, your bug will probably be closed as INSUFFICIENT_DATA.


<pre>
So, once you've seen a bug and determined it's still present in the latest version, it's time to open a Bugzilla.
Greetings.
anaconda installer init version 11.1.0.47 starting
</pre>


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.
== Types of Bugs ==


== Identifying your type of bug ==
There are several types of bugs you might encounter. The four listed here are the most common and are generally easy to identify.


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.
=== Loader Bugs ===


[[Image:Anaconda_BugReporting_loader-stacktrace.png]]
[[Image: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.
If your bug looks like this, you've encountered a problem in the first stage of anaconda, known as the loader. It is written in C, and what you are seeing is a dump of the hex addresses of functions. The numbers don't mean anything to you, but they tell us exactly where the bug is occurring and how we got there.
 
These numbers change every time anaconda or one of the components it depends upon is rebuilt, as the locations of functions in the compiled programs change. In order to diagnose the problem, we will need accurate version numbers as described in the first section, as well as the exact numbers shown on the screen. A common way of getting the numbers without risking a typo is to take a picture of the screen with a camera, and then attach the photo to a bug report.
 
Without all of those numbers, we will be completely unable to fix the bug, so please make sure you get all of them!
 
=== Kernel Bugs ===
 
If your install just stops doing anything, you may have encountered a kernel bug. Try to press ctrl-alt-F4. This should take you over to the fourth virtual console (tty4) unless things are seriously screwed up. If this is the case, you have very likely encountered a kernel bug. This report should be filed against the kernel, not against anaconda. They will likely want a picture of what's on screen, as well as a list of steps you had taken before the problem occurred. However, filing kernel bugs is outside the scope of this document.
 
=== X Bugs ===
 
When anaconda transitions from stage 1 to stage 2, sometimes X will fail to start. Sometimes this results in being given the text mode interface instead of the graphical one, and sometimes all you get is a black screen. These bugs should be filed against xorg-x11, along with /var/X.log.
 
=== Tracebacks ===
 
[[Image:Anaconda_BugReporting_stage2-traceback.png]]
 
Bugs that manifest like the above image are bugs in the second stage of anaconda, or Stage 2. These are easier to file bugs against, thanks to {{package|python-meh}}. What you're seeing is similar to the loader stack trace, but much more informative. You're seeing a Python exception report.
 
Whenever a traceback happens, a file matching {{filename|/tmp/anaconda-tb-*}} will be created containing the traceback, as well as the additional log files.  If you choose to automatically file a bug report, this file will be attached to your bug. This is often the key piece of information we need to fix the bug, but don't go away yet!  Some bugs are weird, and it's always best to get some other information from you in a comment.
 
=== Hardware Errors ===
 
Hardware Errors are a bit of a mixed bag. Sometimes they can manifest like kernel bugs, and sometimes they can look like tracebacks.
 
If you see any lines in your traceback that say "I/O Error", you probably have bad media somewhere (hard drive, CD/DVD, and so on). If you can verify that your media is all just fine before filing the bug it would be helpful; if not that will be the first thing we point out and ask about.
 
== Other Potentially Useful Information ==
 
If you ran into a traceback (and you have a Bugzilla account and networking was working...), you're rather lucky. A bug report with your anaconda-tb-* has been created, and sometimes, that's all we need. But adding more information in a comment can help get your bug fixed faster, or help us reproduce it on-site. If you don't provide us with that information, we're going to have to rely on you to retest the bug for us.
 
If you got a traceback, but cannot use automated bug filing, you can collect the file /tmp/anaconda-tb-* from tty2 (to switch to tty2, press ctrl+alt+f2) and attach it to the bug report.
 
If you didn't get a traceback, this section lists information you might want to include when you file the report.
 
=== Log Files ===
 
Anaconda writes several log files which contain valuable information about what the installer is/was doing.
 
If any files named <code>/tmp/anaconda-tb-*</code> exist, attach it to your bug report. You may ignore the remainder of "Log Files" section.
 
There is a quick way to obtain a single file that includes the content of all of the most important log files (<code>/tmp/anaconda-tb-*</code>):
 
* switch to <code>tty2</code> (press <code>ctrl+alt+f2</code>)
* run the command <pre>killall -USR2 anaconda</pre>
 
If any files named <code>/tmp/anaconda-tb-*</code> exist, attach it to your bug report.  You may ignore the remainder of "Log Files" section.
 
The following log files, all of which are included in <code>anaconda-tb-*</code>, are useful in the event that a failure has occurred:
 
* <code>/tmp/anaconda.log</code>
* <code>/tmp/program.log</code>
* <code>/tmp/storage.log</code>
* <code>/tmp/syslog</code>
 
{{admon/tip|Tip|The contents of all of the above files are included in <code>/tmp/anaconda-tb-*</code>, so there is no need to attach them if you have attached <code>anaconda-tb-*</code>.}}
 
If the failure occurred during package selection or package installation, the following additional files can be very useful (if present):
 
* <code>/tmp/yum.log</code>
* <code>/mnt/sysimage/install.log</code>
* <code>/mnt/sysimage/upgrade.log</code>
 
{{admon/tip|Tip|The contents of all of the above files are included in <code>/tmp/anaconda-tb-*</code>, so there is no need to attach them if you have attached <code>anaconda-tb-*</code>.}}
 
=== Hardware ===
 
Letting us know what hardware you're on can be informative. Don't worry, though, we don't need serial numbers of every piece of metal in your machine. If your bug appears to be with networking, the network card you're using is probably the only thing we need. If you're having X troubles, let us know what video card you're using. If the bug appears in partitioning, tell us what disks and how many.
 
== Kickstart File==
 
If you're installing with kickstart, please include the kickstart file. Make sure to scrub it of any passwords first, though!
 
=== Anaconda Stage ===
 
If anaconda is not able to transition from stage 1 to stage 2 successfully, please mention it, because it's important to make sure that the install was able to get out of the installation source step and actually start anaconda. If you are not sure what the stages are, please refer to [[Anaconda/Stage]] for details.
 
=== Previous Steps ===
 
Always, always useful are the steps you took to cause the problem. It's most useful because it allows us to reproduce the bug and test fixes in our own lab, without leaning on you to test for us. It can also help us connect bugs which might not otherwise appear related.
 
It is rare that language and keyboard are the defining factors for whether your install crashes, but it has been known to happen so please don't leave these out!
 
=== Attached Devices ===
 
If you have any USB or Firewire devices attached to the computer during the install, please include that information. Also, include whether you plugged or unplugged any of them at any point during the install. (If you're wondering, it's a bad idea! Don't do it!)
 
=== Encryption ===
 
If your bug is not a crypto-luks error and you were using encryption, you might want to include that. If it ''is'' a crypto-luks error and you were ''not'' using encryption, ''definitely'' let us know!
 
=== Partitioning Layout ===
 
If you got as far as partitioning, please let us know what your layout was if it was a custom one. You should also include whether the drive or drives contained previous information that was being wiped, what was on it, and whether there are any other operating systems installed on the drive(s).
 
== Writing the Report ==
 
So, now that you've thought about what information you might want to include, it is time to actually write your report (or for tracebackers, to add a comment). You should go to [https://bugzilla.redhat.com/enter_bug.cgi] to file a new bug.
 
Navigate the filing system for the correct release (RHEL versus Fedora) you encountered the bug in to arrive at the information screen. There are a couple crucial fields to fill out, and some that should be left alone.
 
The component must be set as anaconda, or we won't see the bug unless someone else happens to notice and sends it to us. The version number should be which release you used; if you installed with Rawhide just select that one. You can narrow down the platform to the arch you tried if you wish, but it's not crucial.
 
Severity and Priority should '''not''' be changed. They are used by developers and people in QA, and should not be touched by reporters. Yes, even if you think your bug is the worst bug ever.


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.
After the top section, scroll down until you see the "Summary" field. This will be the title of your bug, so please try to make it useful. "anaconda crash" and "Bad: Install Failed" are completely unhelpful as titles, because they tell us nothing about what's going on. Please try to include keywords important to your bug, such as "lvm" or "grub". You can also put in the error message you received.


[[Image:Anaconda_BugReporting_stage2-backtrace.png]]
Note: If your bug is a UI bug, feel free to use a descriptive title. "Use of F12 is inconsistent in the installer" is a great title.


<picture of a backtrace in text mode>
The last thing you need to enter is the description, and there are different ways to do this.


<picture of a backtrace before stage2 is up>
=== To Form or Not to Form? ===


If your bug looks like any of these screenshots, 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.
By default, new bug reports include in the description section a standard format for your report. You can use this if you wish, but it is not required. '''If you choose not to use the format, please delete it!'''


In the first two cases, 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 you choose to follow the form, your information should be divided up as it requests. The first part asks for a description of the problem. Then the version number, then how reproducible it is. If you haven't tried to reproduce the bug, please say so instead of guessing.


In the third case, what you see is what you get (unless it's an extremely long traceback). Here, taking a picture is your best option.  You may need to take several if the traceback is long and goes up the screen. All that information will be useful in our debugging.
Then the steps to reproduce - as was said above, we really like getting these. The more specific and detailed you can be about what you did, the better. For example, if you're getting a bug after making a custom partition layout, "Made custom layout" is not helpful at all, "Made custom layout that looked like this" is pretty helpful, and "created /boot on ext3 with 200M space, created a 200M RAID and deleted it, created 4 RAIDs with remaining space, combined them all into a RAID10 and mounted encrypted /" is fantastic. Sometimes we get bugs that only appear when you create then delete a partition, and there would be no way to diagnose that problem from the first two examples.


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.
Actual results are obviously what happened, and expected results are what was expected to happen - generally, for anaconda not to crash.


== What information do we need? ==
In additional info, feel free to include any of the information described in section 3.


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:
=== Specificity ===


* The traceback information explained earlier - either a picture of the loader stack trace, or the complete python exception report.
It is really important that you be as specific as possible in your terminology. An upgrade is '''not''' the same thing as an install, and using the two terms interchangeably will only cause us to tear our hair out in frustration.
* 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:
Things you should not confuse:
- upgrade vs install
- LV vs PV vs VG
- dmraid vs mdraid
- '''The order of your steps'''


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


'''Were you partitioning your disks?'''  Please also include:
We know. You just wanted to install, and something went wrong. Maybe you didn't get the new system, or maybe your old system got wiped.


* What sort of partitioning scheme you were trying to set up, and what kinds of filesystems you wanted to make.
But no matter what, ''being short or snarky with us will not help''. We don't enjoy dealing with people who are going to be rude, and when we have so many bugs we have to deal with, we're likely to prioritize ones where the reporters remember that we're human too... and only human.
* 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:
We do not make a point of wasting your time, so please don't waste ours. If we ask for a piece of information, it's because we need it to help figure out or fix the bug you've seen. Please don't try to tell us that you don't have it anymore and aren't willing to try another install to get it, but that we should be able to figure out your problem from the information you provided. If we could, we wouldn't have asked.


* What sort of networking hardware you have.
At the same time, we are swamped with bugs, and some do get overlooked. If it has been a while since you heard anything about your bug, feel free to comment and ask what the status is. However, please ''don't'' say things like "I guess I now know how much the anaconda developers care about fixing bugs!" It's just petty.
* What you were trying to do.


== Writing the bug report ==
== What Happens Next? ==


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.
Once you've filed your bug report, you get to wait. How exciting! There's no way to tell how long your bug will be open - some are fixed in hours and are in rawhide the following day, and some (well, one) are waiting 10 years because somebody else needs to support something before we can.


* '''Version:'''  Unless you are using a particular release, please use the devel version.  Test releases should be filed under      the devel version as well.
When we get to your bug, we may ask you for more information, to try running a command and giving us the output, or to try an update image. It's most helpful if your computer is still available for testing since even with steps there's no guarantee our hardware will reproduce the bug, so reporting a bug and then immediately installing something else means your bug will most likely not get fixed.
* '''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? ==
It's worth noting, however, that up until partitioning nothing that you do is permanent. You can run anaconda all you want and test everything up through the partitioning screen, so if your bug happened before then you won't be risking your system by trying another install.


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.
Please, don't assume that somebody else will file a bug if you don't. Rawhide doesn't have a very large testing base, so while bugs that affect all installs will be filed, ones that happen semi-rarely might not be. If that happens, the bugs will make it into an official release and will be unleashed upon a large group of users. It's so much better for everyone if bugs can be reported before, rather than after, they make it into a release.


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.
[[Category:Anaconda]]
[[Category:Debugging|I]]

Latest revision as of 00:34, 8 August 2018


Narrowing it Down

Before doing anything else, please try to figure out if you're testing the latest version of anaconda - this goes for all software products. If you're running into a problem in F10 while we're developing F12, a bug report will not be very helpful and the problem may even be fixed already. If you ever encounter a bug that is not in the latest anaconda, please locate the newest one and try that.

To check which version of anaconda you're running, you need only watch the screen when anaconda starts up. It will print something like 

Greetings.
anaconda installer init version 11.5.0.47 starting

And that's your version of anaconda!

The other useful number is the tree. If you're using an official release, all we need is which Fedora you're installing. If, on the other hand, you're using the development tree (Rawhide), there are two ways to discover which tree you're using. Often the installation source will have a date in the path, which will tell us which build to look at. If your install source does not have a date, its .treeinfo file should contain a timestamp and a version number.

If you cannot remember what you were using when you encountered the bug, please try again with the newest one. If you don't, we're just going to have to ask you to do so and it would save everyone time not to deal with that.

If you are unwilling to try the newest rawhide to see if the bug is still present, especially if the rawhide you were using is an old one, your bug will probably be closed as INSUFFICIENT_DATA.

So, once you've seen a bug and determined it's still present in the latest version, it's time to open a Bugzilla.

Types of Bugs

There are several types of bugs you might encounter. The four listed here are the most common and are generally easy to identify.

Loader Bugs

File:Anaconda BugReporting loader-stacktrace.png

If your bug looks like this, you've encountered a problem in the first stage of anaconda, known as the loader. It is written in C, and what you are seeing is a dump of the hex addresses of functions. The numbers don't mean anything to you, but they tell us exactly where the bug is occurring and how we got there.

These numbers change every time anaconda or one of the components it depends upon is rebuilt, as the locations of functions in the compiled programs change. In order to diagnose the problem, we will need accurate version numbers as described in the first section, as well as the exact numbers shown on the screen. A common way of getting the numbers without risking a typo is to take a picture of the screen with a camera, and then attach the photo to a bug report.

Without all of those numbers, we will be completely unable to fix the bug, so please make sure you get all of them!

Kernel Bugs

If your install just stops doing anything, you may have encountered a kernel bug. Try to press ctrl-alt-F4. This should take you over to the fourth virtual console (tty4) unless things are seriously screwed up. If this is the case, you have very likely encountered a kernel bug. This report should be filed against the kernel, not against anaconda. They will likely want a picture of what's on screen, as well as a list of steps you had taken before the problem occurred. However, filing kernel bugs is outside the scope of this document.

X Bugs

When anaconda transitions from stage 1 to stage 2, sometimes X will fail to start. Sometimes this results in being given the text mode interface instead of the graphical one, and sometimes all you get is a black screen. These bugs should be filed against xorg-x11, along with /var/X.log.

Tracebacks

Bugs that manifest like the above image are bugs in the second stage of anaconda, or Stage 2. These are easier to file bugs against, thanks to python-meh. What you're seeing is similar to the loader stack trace, but much more informative. You're seeing a Python exception report.

Whenever a traceback happens, a file matching /tmp/anaconda-tb-* will be created containing the traceback, as well as the additional log files. If you choose to automatically file a bug report, this file will be attached to your bug. This is often the key piece of information we need to fix the bug, but don't go away yet! Some bugs are weird, and it's always best to get some other information from you in a comment.

Hardware Errors

Hardware Errors are a bit of a mixed bag. Sometimes they can manifest like kernel bugs, and sometimes they can look like tracebacks.

If you see any lines in your traceback that say "I/O Error", you probably have bad media somewhere (hard drive, CD/DVD, and so on). If you can verify that your media is all just fine before filing the bug it would be helpful; if not that will be the first thing we point out and ask about.

Other Potentially Useful Information

If you ran into a traceback (and you have a Bugzilla account and networking was working...), you're rather lucky. A bug report with your anaconda-tb-* has been created, and sometimes, that's all we need. But adding more information in a comment can help get your bug fixed faster, or help us reproduce it on-site. If you don't provide us with that information, we're going to have to rely on you to retest the bug for us.

If you got a traceback, but cannot use automated bug filing, you can collect the file /tmp/anaconda-tb-* from tty2 (to switch to tty2, press ctrl+alt+f2) and attach it to the bug report.

If you didn't get a traceback, this section lists information you might want to include when you file the report.

Log Files

Anaconda writes several log files which contain valuable information about what the installer is/was doing.

If any files named /tmp/anaconda-tb-* exist, attach it to your bug report. You may ignore the remainder of "Log Files" section.

There is a quick way to obtain a single file that includes the content of all of the most important log files (/tmp/anaconda-tb-*):

  • switch to tty2 (press ctrl+alt+f2)
  • run the command 
    killall -USR2 anaconda

If any files named /tmp/anaconda-tb-* exist, attach it to your bug report. You may ignore the remainder of "Log Files" section.

The following log files, all of which are included in anaconda-tb-*, are useful in the event that a failure has occurred:

  • /tmp/anaconda.log
  • /tmp/program.log
  • /tmp/storage.log
  • /tmp/syslog
Tip
The contents of all of the above files are included in /tmp/anaconda-tb-*, so there is no need to attach them if you have attached anaconda-tb-*.

If the failure occurred during package selection or package installation, the following additional files can be very useful (if present):

  • /tmp/yum.log
  • /mnt/sysimage/install.log
  • /mnt/sysimage/upgrade.log
Tip
The contents of all of the above files are included in /tmp/anaconda-tb-*, so there is no need to attach them if you have attached anaconda-tb-*.

Hardware

Letting us know what hardware you're on can be informative. Don't worry, though, we don't need serial numbers of every piece of metal in your machine. If your bug appears to be with networking, the network card you're using is probably the only thing we need. If you're having X troubles, let us know what video card you're using. If the bug appears in partitioning, tell us what disks and how many.

Kickstart File

If you're installing with kickstart, please include the kickstart file. Make sure to scrub it of any passwords first, though!

Anaconda Stage

If anaconda is not able to transition from stage 1 to stage 2 successfully, please mention it, because it's important to make sure that the install was able to get out of the installation source step and actually start anaconda. If you are not sure what the stages are, please refer to Anaconda/Stage for details.

Previous Steps

Always, always useful are the steps you took to cause the problem. It's most useful because it allows us to reproduce the bug and test fixes in our own lab, without leaning on you to test for us. It can also help us connect bugs which might not otherwise appear related.

It is rare that language and keyboard are the defining factors for whether your install crashes, but it has been known to happen so please don't leave these out!

Attached Devices

If you have any USB or Firewire devices attached to the computer during the install, please include that information. Also, include whether you plugged or unplugged any of them at any point during the install. (If you're wondering, it's a bad idea! Don't do it!)

Encryption

If your bug is not a crypto-luks error and you were using encryption, you might want to include that. If it is a crypto-luks error and you were not using encryption, definitely let us know!

Partitioning Layout

If you got as far as partitioning, please let us know what your layout was if it was a custom one. You should also include whether the drive or drives contained previous information that was being wiped, what was on it, and whether there are any other operating systems installed on the drive(s).

Writing the Report

So, now that you've thought about what information you might want to include, it is time to actually write your report (or for tracebackers, to add a comment). You should go to [1] to file a new bug.

Navigate the filing system for the correct release (RHEL versus Fedora) you encountered the bug in to arrive at the information screen. There are a couple crucial fields to fill out, and some that should be left alone.

The component must be set as anaconda, or we won't see the bug unless someone else happens to notice and sends it to us. The version number should be which release you used; if you installed with Rawhide just select that one. You can narrow down the platform to the arch you tried if you wish, but it's not crucial.

Severity and Priority should not be changed. They are used by developers and people in QA, and should not be touched by reporters. Yes, even if you think your bug is the worst bug ever.

After the top section, scroll down until you see the "Summary" field. This will be the title of your bug, so please try to make it useful. "anaconda crash" and "Bad: Install Failed" are completely unhelpful as titles, because they tell us nothing about what's going on. Please try to include keywords important to your bug, such as "lvm" or "grub". You can also put in the error message you received.

Note: If your bug is a UI bug, feel free to use a descriptive title. "Use of F12 is inconsistent in the installer" is a great title.

The last thing you need to enter is the description, and there are different ways to do this.

To Form or Not to Form?

By default, new bug reports include in the description section a standard format for your report. You can use this if you wish, but it is not required. If you choose not to use the format, please delete it!

If you choose to follow the form, your information should be divided up as it requests. The first part asks for a description of the problem. Then the version number, then how reproducible it is. If you haven't tried to reproduce the bug, please say so instead of guessing.

Then the steps to reproduce - as was said above, we really like getting these. The more specific and detailed you can be about what you did, the better. For example, if you're getting a bug after making a custom partition layout, "Made custom layout" is not helpful at all, "Made custom layout that looked like this" is pretty helpful, and "created /boot on ext3 with 200M space, created a 200M RAID and deleted it, created 4 RAIDs with remaining space, combined them all into a RAID10 and mounted encrypted /" is fantastic. Sometimes we get bugs that only appear when you create then delete a partition, and there would be no way to diagnose that problem from the first two examples.

Actual results are obviously what happened, and expected results are what was expected to happen - generally, for anaconda not to crash.

In additional info, feel free to include any of the information described in section 3.

Specificity

It is really important that you be as specific as possible in your terminology. An upgrade is not the same thing as an install, and using the two terms interchangeably will only cause us to tear our hair out in frustration.

Things you should not confuse: 

- upgrade vs install
- LV vs PV vs VG
- dmraid vs mdraid
- The order of your steps

Tone

We know. You just wanted to install, and something went wrong. Maybe you didn't get the new system, or maybe your old system got wiped.

But no matter what, being short or snarky with us will not help. We don't enjoy dealing with people who are going to be rude, and when we have so many bugs we have to deal with, we're likely to prioritize ones where the reporters remember that we're human too... and only human.

We do not make a point of wasting your time, so please don't waste ours. If we ask for a piece of information, it's because we need it to help figure out or fix the bug you've seen. Please don't try to tell us that you don't have it anymore and aren't willing to try another install to get it, but that we should be able to figure out your problem from the information you provided. If we could, we wouldn't have asked.

At the same time, we are swamped with bugs, and some do get overlooked. If it has been a while since you heard anything about your bug, feel free to comment and ask what the status is. However, please don't say things like "I guess I now know how much the anaconda developers care about fixing bugs!" It's just petty.

What Happens Next?

Once you've filed your bug report, you get to wait. How exciting! There's no way to tell how long your bug will be open - some are fixed in hours and are in rawhide the following day, and some (well, one) are waiting 10 years because somebody else needs to support something before we can.

When we get to your bug, we may ask you for more information, to try running a command and giving us the output, or to try an update image. It's most helpful if your computer is still available for testing since even with steps there's no guarantee our hardware will reproduce the bug, so reporting a bug and then immediately installing something else means your bug will most likely not get fixed.

It's worth noting, however, that up until partitioning nothing that you do is permanent. You can run anaconda all you want and test everything up through the partitioning screen, so if your bug happened before then you won't be risking your system by trying another install.

Please, don't assume that somebody else will file a bug if you don't. Rawhide doesn't have a very large testing base, so while bugs that affect all installs will be filed, ones that happen semi-rarely might not be. If that happens, the bugs will make it into an official release and will be unleashed upon a large group of users. It's so much better for everyone if bugs can be reported before, rather than after, they make it into a release.

Retrieved from "https://fedoraproject.org/w/index.php?title=How_to_debug_installation_problems&oldid=523249"