トラブルシューティング

This page is a translated version of the page Troubleshooting and the translation is 53% complete.

Other languages:

このページでは、トラブルを解消したり Gentoo のセットアップの際の支障を解決したりするための（特に新たな）技術やツールに関する情報を提供しています。また、比較的複雑な支障にとりくむために、課題解決のために努力したり助けを求めたりする際のより適切な情報収集技術について提供しています。

この記事では、Gentoo ハンドブックを読み Gentoo を扱ううえでの基礎的な理解があることを前提にしています。

どこに助けを求めればいいか

Gentooには、豊富な情報量のwikiがかなり多くあります。古い、または時代遅れの情報を含んでいる記事が存在することに注意する必要がありますが、Gentooを使用する際、wikiの記事を読むことは常に重要なステップです。

公式のGentooWiki
一般的な習慣や問題に対する知識ベース,

IRCでは、#gentoo (webchat)が一般的な問題に対する推奨されるチャンネルです。多分これが回答を得るのに最も速いです．

IRCチャンネルではアクティブ状態でいることが必要なため、ブラウザを閉じてもメッセージが残り続けるフォーラムやメーリングリストにメッセージを残す方を好むユーザがいるかもしれません。回答を得られた時、通知（通常はeメールによって）が送られてきます。

もしそれでも駄目で、Gentooの何かが壊れているようであれば、既に何か報告されているかを確認したり、また必要であれば新しいバグ報告を作成するのにGentooのバグトラッカーが良いリソースとなります。これはGentooの開発者とコンタクトを取るのに非常に効率的な方法で、これによって与えられたフィードバックを問題の状況の改善や問題の解決に使用することができます。

プログラム

これは、非常に推奨されているツールのコレクションです：

パッケージ管理

パッケージ	説明
app-portage/gentoolkit	Gentoo とやり取りするためのツール群を提供します; 利用価値の高いequery、eclean、euse そして eshowkw を含みます。さらなる情報についてはそれらの man ページを見てください。
app-portage/eix	portage にパッケージを問い合わせるツールである eix を提供します。
app-portage/pfl	どのパッケージが与えられたファイルを含むかを問い合わせるツールである e-file を提供します; オンライン検索を使用するので、インストールされていないパッケージに対しても動作します。
app-portage/genlop	emerge ログを解析するツールである genlop を提供します; 特定のパッケージがいつインストールまたはアップデートされたかを知るために、そしてそれらがコンパイルにどれだけかかったかを確認するのに便利です。
app-portage/elogv	emerge ログを閲覧するための ncurses ベースのインターフェースである elogv を提供します。

ハードウェア

パッケージ	説明
sys-apps/pciutils	PCI デバイスに関する情報を収集するツールである lspci を提供します。
sys-apps/usbutils	USB デバイスに関する情報を収集するツールである lsusb を提供します。

監視

パッケージ	説明
sys-process/htop	プロセスを監視するためのツールである htop を提供します。top と似ていますが、より先進的です。
sys-process/iotop	プロセス毎の IO アクティビティを監視するための top 風ツールである iotop を提供します。
net-analyzer/nettop	プロトコル、ポート、プロセス毎のネットワークトラフィックを調査するための top 風ツールである nettop を提供します。

その他

パッケージ	説明
app-text/wgetpaste	テキストを pastebin に直接アップロードするためのツールである wgetpaste を提供します。
net-irc/weechat	シンプルなテキストベースの IRC クライアントである weechat を提供します。

第一段階

問題を解決策に作り変えるためには、まず十分に問題を理解する必要があります。問題が明確でなければ、解決策を思い付くことは不可能であるか、そうでなくても非常に困難なことになるでしょう。的確かつ詳細に問題を記述することは、その問題にとっての最良の解決策をもたらす助けになるでしょう。

問題を特定する

この部分は簡単なことのように見えるかもしれませんが、これ抜きにはどんなトラブルシューティングもほとんど不可能になるでしょう。

いくつかのことをメモしてください:

この問題はハードウェアに関するものですか、それともソフトウェアに関するものですか？
この問題の原因となるかもしれない何かをしたり、または最近変更したりしましたか？
この問題に関係する追加の情報を収集することはできますか？

何らかの形式での詳細の保持、ログ、同じ問題に直面した他の人の情報等は、貴重なものとなりえ、問題についてのよい概観をもたらします。

ハードウェア関連

ドライバ

ハードウェアのドライバ問題は IRC でもっともよく報告される問題のひとつです。

First and foremost, identify what the hardware is that is causing problems. lspci and lsusb are great tools for this purpose. For demonstration purposes, we'll be looking at an Ethernet card as the troublesome device.

適切なドライバの特定

First look with lspci and find the device information:

root #lspci

 03:00.0 Ethernet controller: Marvell Technology Group Ltd. 88E8071 PCI-E Gigabit Ethernet Controller (rev 16)

It is also possible to use the -n option to give a short-hand notation (which might be easier to search for on the Internet):

root #lspci -n

 03:00.0 0200: 11ab:436b (rev 16)

The model name (0200) and vendor/model (11ab:436b) can be used to look up the device on a place like WikiDevi or Debian HCL to find the right driver to use in Linux.

ドライバが読み込まれているか確認する

Getting the driver is less than half of the battle. Most of the trouble with drivers is making sure that they are loaded and operating correctly.

Relying on our friend lspci again, run:

root #lspci -k

 03:00.0 Ethernet controller: Marvell Technology Group Ltd. 88E8071 PCI-E Gigabit Ethernet Controller (rev 16)
 	Subsystem: Acer Incorporated [ALI] Device 014e
 	Kernel driver in use: sky2

Note that here, an indicator is given that a driver is in use. If not, then no driver has claimed responsibility over this hardware. Assuming the driver was built as a module rather than built-in, try modprobe <modulename> to attempt loading the right module. If the driver was built-in, consider making it a module, because modules can be loaded with modprobe and unloaded with modprobe -r which saves on number reboots while debugging the issue.

ドライバをトラブルシュートする

Compile the driver as a module, then capture the output it generates when the module is loaded. Make sure to first remove all modules that depend on the driver (see lsmod).

The following command will compare the dmesg output after removing the module (in this example, r8169) with the output after adding the module again, effectively showing the messages that were added (lines starting with +).

root #diff -u <(modprobe -r r8169; dmesg) <(sleep 1; modprobe r8169; dmesg) | grep ^+

The most common issue is missing firmware. If a message shows up that informs the administrator about missing firmware, grab either sys-kernel/linux-firmware or a specific firmware package from Portage and install it. After the firmware installation, unload and load the kernel module again to see if this fixes the situation.

ソフトウェア関連

Portage 関連

Dependency graph slot conflicts

Occasionally, messages like this occur when trying to emerge a package:

コード 依存関係グラフのエラー

!!! Multiple package instances within a single package slot have been pulled
!!! into the dependency graph, resulting in a slot conflict:

Generally, this means that the packages listed have multiple requested versions in the dependency graph. And fortunately most, if not all, cases allow to resolve it by manually upgrading to the highest requested version. So assuming that the following message was received:

コード 依存関係グラフのエラーの例

app-emulation/emul-linux-x86-xlibs:0 
(app-emulation/emul-linux-x86-xlibs-20120127::gentoo, installed) pulled in by 
~app-emulation/emul-linux-x86-xlibs-20120127 required by (app-emulation/emul-linux-x86-medialibs-20120127::gentoo, installed) 
(and 2 more with the same problem) 
 
(app-emulation/emul-linux-x86-xlibs-20120520::gentoo, ebuild scheduled for merge) pulled in by 
>=app-emulation/emul-linux-x86-xlibs-20120520 required by (net-im/skype-2.2.0.35-r99::gentoo, ebuild scheduled for merge) 
~app-emulation/emul-linux-x86-xlibs-20120520 required by (app-emulation/emul-linux-x86-medialibs-20120520::gentoo, ebuild scheduled for merge)

The most recent version desired is 20120520, so:

root #emerge --ask --oneshot =app-emulation/emul-linux-x86-xlibs-20120520

Often, it's advantageous to one-shot (--oneshot or -1) all of the conflicts at once because they sometimes depend on one another (see also World set).

Here is another example of a block:

コード Example of a block conflict

app-text/poppler:0
 
 (app-text/poppler-0.24.5::gentoo, installed) pulled in by
   app-text/poppler:0/44=[xpdf-headers(+)] required by (dev-tex/luatex-0.76.0::gentoo, installed)
   app-text/poppler:0/44=[cxx,jpeg,lcms,tiff,xpdf-headers(+)] required by (net-print/cups-filters-1.0.43::gentoo, installed)
 
 (app-text/poppler-0.24.3::gentoo, ebuild scheduled for merge) pulled in by
   >=app-text/poppler-0.12.3-r3:0/43= required by (app-text/texlive-core-2013-r1::gentoo, installed)
   poppler:0/43

There should be no problem changing poppler versions. Note that app-text/texlive-core does not require a specific version of poppler, but it needs to be rebuild with whatever version is used:

root #emerge --ask --oneshot =app-text/poppler-0.24.5 app-text/texlive-core

Here is another example that could have resulted in a blockage:

root #emerge --ask --verbose --update --newuse --deep @world

コード Example of an update conflict

sys-power/cpupower:0

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 KiB

WARNING: One or more updates/rebuilds have been skipped due to a dependency conflict:

sys-power/cpupower:0

  (sys-power/cpupower-4.9.0-r1:0/0::gentoo, ebuild scheduled for merge) conflicts with
    <sys-power/cpupower-4.7 required by (mate-base/mate-applets-1.12.1-r4:0/0::gentoo, installed)
    ^                   ^^^

Nothing to merge; quitting.

Portage warns about an update that can not be performed, however, there is no issue because this update is not required by a package. More precisely, the update must be skipped because mate-base/mate-applets-1.12.1-r4 requires a version of sys-power/cpupower package lower than 4.7.

追加の情報を収集する

When seeking help, more times than never additional information will be asked, such as the output of a command. Some of these produce dozens or hundreds of lines of text - too much to be suitable for pasting into IRC chat rooms, such as the Gentoo support channel on Freenode. That's where wgetpaste comes in handy - it allows users to post short links that contain long output.

Make sure that app-text/wgetpaste is installed:

root #emerge --ask wgetpaste

For instance, to show the contents of /etc/conf.d/net, using wgetpaste is as simple as:

user $wgetpaste /etc/conf.d/net

Or let's say that someone needs the detailed output of an lspci command is:

root #wgetpaste -c 'lspci -nnk'

Sometimes it is necessary to redirect stderr to stdout so that error messages can be pasted as well. That can be done like this:

root #wgetpaste -c 'emerge -pv <package>'

These return a link to a pastebin site page that can be easily shared with someone to get help.

Things to consider pasting:

In case of hardware problems or kernel issues:

user $wgetpaste /usr/src/linux/.config

In case of portage issues:

root #emerge --verbose --info | wgetpaste

In case of package installation failures:

root #wgetpaste /var/tmp/portage/<category>/<package>-<version>/temp/build.log

In case of Xorg issues:

user $wgetpaste /var/log/Xorg.0.log

In case all installed packages on the system needs to be provided:

root #eix-update && eix-installed all

Wrapping things together

Below is a shell function that can be used to have several commands executed and their output processed by a single wgetpaste command so that only one URL needs to be provided to the user or developer that wants to help out:

root #

wgetpaste -i -c "lspci -nnk" -c "lsusb" -c "cat /usr/src/*$(uname -r)/.config"\
 -c "cat /var/log/Xorg.0.log" -c "dmesg" -c "eix-update" -c "eix-installed all"

Please do not use pastebin services on the gentoo-user mailing list

Most pastebin services expire old pastes periodically (not to mention that pastebin services are hardly profitable, and close down all the time) whereas mailing list messages are archived in multiple places and are referenced for years. If the relevant output is short, or can be trimmed, then copy and paste it into the body of the email - longer output can be directed into a text file and added as a plain attachment.

Forming a solution

With a good description of the problem, a complete history of actions and all sorts of debugging data (problem details, hardware / software information, logs, backtraces and more) a good set of useful data is available to look for a solution.

In general, repeat the following steps to come to a solution:

Get an idea where the problem might be, think about possible causes.
If there are no obvious areas to look into, become more acquainted with the related areas or ask an expert more about it.
Sometimes it is necessary to make assumptions to proceed. When assumptions are made, put it to the test: false assumptions should not make users and developers blind of other causes.
Obtain additional debugging information in the area of a problem, or perform tests.

Often this will lead to multiple possible causes. It is important to test them (to verify it is the actual cause or not) and therefore test them individually; this is also known as "divide and conquer".

Let's say a problem like "my browser sometimes displays white pages when I boot" comes up and a lot of details are already known about it, then there may be number of possible causes:

Is this because the browser was improperly closed when the system rebooted?

Verify this by killing the process and pulling the plug several times, each time checking if the pages are white after booting again. If this is a cause, is it the actual cause or are there other causes?

Is this the result of a specific browser version being broken?

Try older or newer versions for a few days or reboots and see if they are broken as well.

And so on...

With the additional information, dare to think about more specific causes:

Does a certain pinned tab X that loads plugin Y break the system?

Unpin the tab so it doesn't open on launch anymore or disable the plugin, see if this keeps the problem away.

Graphical issues were reported as well, might this maybe mean this is caused by the video drivers?

Try a different version for those drivers, or alternative drivers if available.

As each possible cause is investigated, the actual cause of the problem might come closer and closer.

And in the end, if the cause is still not found, the Where to get help resources at the top of this article yield a multitude of places with people that are looking forward to help; make them happy with a careful problem description and mentioning what has already been tried so far, it'll help them help out.