Live manual Debian Live

# Debian Live Manual

# Reporting bugs

661

# 14. Reporting bugs

662

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.

663

For the impatient:

664

- First check whether the bugs has been reported already. You can see the full list of bugs that are assigned to the live-team at ‹https://bugs.debian.org/cgi-bin/pkgreport.cgi?maint=debian-live%40lists.debian.org›.

665

- Before submitting a bug report always try to reproduce the bug with the most recent versions of the packages of live-build, live-boot, live-config and live-tools that you're using.

666

- 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.

667

14.1 Known issues

668

Currently known issues are listed in the BTS at ‹https://bugs.debian.org/cgi-bin/pkgreport.cgi?maint=debian-live%40lists.debian.org›.

669

Note: 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.

670

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.

671

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, you can always try the following: If a build fails when the target distribution is testing, try unstable. If unstable does work, revert to testing and pin the newer version of the failing package from unstable (see APT pinning for details).

672

14.2 Do the research

673

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.

674

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.

675

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.

676

14.3 Rebuild from scratch

677

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.

678

14.4 Use up-to-date packages

679

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. If possible, try to reproduce the bug with the newest code from source, see Installation for details.

680

14.5 Collect information

681

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.

682

To make the most out of your bug report, we require at least the following information:

683

- Architecture of the host system

684

- Distribution of the host system

685

- Version of live-build on the host system

686

- Version of debootstrap on the host system

687

- Architecture of the live system

688

- Distribution of the live system

689

- Version of live-boot on the live system

690

- Version of live-config on the live system

691

- Version of live-tools on the live system

692

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 for details).

693

# lb build 2>&1 | tee build.log

694

At boot time, live-boot and live-config store their logfiles in `/var/log/live/`. Check them for error messages.

695

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).

696

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`.

697

14.6 Isolate the failing case if possible

698

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.

699

14.7 Use the correct package to report the bug against

700

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.

701

However, we would appreciate it if you try to narrow it down according to where the bug appears.

702

14.7.1 At build time while bootstrapping

703

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.

704

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.

705

14.7.2 At build time while installing packages

706

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.

707

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.

708

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.

709

14.7.3 At boot time

710

If your image does not boot, please report it to the mailing list together with the information requested in 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.

711

14.7.4 At run time

712

If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in live-config.

713

14.8 Where to report bugs

714

The Debian Live 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.

715

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.