رفع خطاهای رایج در Gentoo — راهنمای عیبیابی جامع
راهنمای کامل عیبیابی Gentoo: مشکلات بوت (GRUB rescue، kernel panic، initramfs)، شبکه، بستههای مسدودشده، نمایشگر، صدا و دیسک؛ هر کدام با نشانه، دستور تشخیص و راهحل.
این مستند راهنمای عیبیابی جامع Gentoo است و مشکلات بوت، شبکه، بستهها، نمایشگر، صدا و دیسک را پوشش میدهد. هر بخش با نشانه (symptom)، دستور تشخیص و راهحل ارائه شده است. پیش از هر چیز، خواندن لاگها را بیاموزید — اکثر خطاها در لاگ مشخص میشوند.
ابزارهای پایه عیبیابی
| منبع لاگ | دستور مشاهده | کاربرد |
|---|---|---|
| ژورنال systemd | journalctl -b | رخدادهای بوت فعلی |
| ژورنال بوت قبلی | journalctl -b -1 | اگر بوت قبلی کرش کرده |
| لاگ کرنل | dmesg | سختافزار، درایور |
| لاگ عمومی | /var/log/messages | OpenRC، سرویسها |
| لاگ Xorg | /var/log/Xorg.0.log | سرور X11 |
| لاگ emerge | /var/log/emerge.log | نصب بسته |
| لاگ Portage | /var/log/portage/elog/summary.log | هشدارها و elog |
# ترکیبی: خطاهای امروز
journalctl --since today -p err
# خروجی:
# Sep 12 10:23:45 gentoo-host kernel: nvidia: module verification failed
# Sep 12 10:24:01 gentoo-host sshd[1234]: error: PAM authentication failure
# Sep 12 10:25:12 gentoo-host kernel: EXT4-fs error (device sda3)همیشه از dmesg شروع کنید
اگر سختافزار یا درایور مشکل دارد، dmesg نخستین منبع است. خواندن ۵۰ خط آخر میتواند مشکل را مشخص کند:
dmesg --level=err,warn | tail -50مشکلات بوت
۱. GRUB rescue prompt
grub rescue>دلیل: GRUB فایلهای خود را پیدا نمیکند؛ معمولاً پس از تغییر پارتیشنها یا نصب سیستمعامل دیگری رخ میدهد. راهحل:
grub rescue> ls
(hd0) (hd0,gpt1) (hd0,gpt2) (hd0,gpt3)
grub rescue> ls (hd0,gpt3)/boot/grub
grub rescue> set prefix=(hd0,gpt3)/boot/grub
grub rescue> set root=(hd0,gpt3)
grub rescue> insmod normal
grub rescue> normalپس از بوت، GRUB را دوباره نصب کنید:
grub-install /dev/sda # یا برای UEFI
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Gentoo
grub-mkconfig -o /boot/grub/grub.cfgبرای جزئیات بیشتر به آموزش GRUB مراجعه کنید.
۲. Kernel panic — VFS unable to mount root fs
VFS: Cannot open root device "UUID=..." or unknown-block(0,0)
Please append a correct "root=" boot option; here are the available partitions:
Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)دلیل: هسته نمیتواند ریشه را پیدا کند؛ یا UUID اشتباه است، یا درایور SATA/SCSI/EXT4 در هسته نیست، یا initramfs وجود ندارد. راهحل:
# بررسی fstab
cat /etc/fstab
# UUID باید با خروجی blkid مطابق باشد
blkid /dev/sda3
# بررسی پارامتر بوت در GRUB
cat /boot/grub/grub.cfg | grep linux
# باید خط root=UUID=... وجود داشته باشد
# اگر initramfs لازم است (RAID، LVM، encrypted root):
emerge --ask sys-kernel/dracut
dracut --force
# و اطمینان از فعالبودن initramfs در /etc/default/grub:
# GRUB_DISABLE_DRACUT=true را غیرفعال کنید
grub-mkconfig -o /boot/grub/grub.cfginitramfs برای ریشه رمزنگاریشده الزامی است
اگر ریشه را با LUKS رمزنگاری کردهاید، بدون initramfs نمیتوانید بوت کنید. آن را با dracut یا genkernel --initramfs بسازید. در آموزش Manual Kernel و آموزش Distribution Kernel جزئیات آن آمده است.
۳. systemd در حالت emergency میماند
You are in emergency mode. After logging in, type "journalctl -xb" to view system logs.
Give root password for maintenance
(or press Control-D to continue):دلیل: یک سرویس بحرانی (مانند fsck، mount، quota) شکست خورده است. راهحل:
# وارد شوید با رمز root
# لاگ را بخوانید
journalctl -xb | tail -50
# شایعترین دلیل: fstab اشتباه
mount -o remount,rw /
nano /etc/fstab
# خط مشکلدار را اصلاح یا کامنت کنید
# یا سرویس مشکلدار را disable کنید
systemctl disable <bad-service>
systemctl default # ادامه بوت۴. صفحه سیاه پس از GRUB (بدون خروجی)
دلیل: هسته با پارامتر quiet اجرا شده و خطا پنهان مانده است. راهحل:
# در GRUB menu، e را بزنید، خط linux را ویرایش کنید
# quiet و splash را حذف کنید، init=/bin/bash اضافه کنید
# Ctrl+X برای بوت
# حالا در shell بهصورت مستقیم:
mount -o remount,rw /
# لاگها را بررسی کنید
journalctl -b -1
# مشکل را اصلاح کنید و rebootمشکلات شبکه
۱. هیچ IP دریافت نمیکنم
# بررسی رابط
ip link show
# 2: enp3s0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN
# بالا آوردن رابط
ip link set enp3s0 up
# درخواست DHCP
dhcpcd enp3s0
# یا
rc-service net.enp3s0 start # OpenRC
# بررسی
ip addr show enp3s0
# باید خط inet داشته باشداگر رابط وجود ندارد، درایور کارت شبکه در هسته نیست:
lspci | grep -i ethernet
# 03:00.0 Ethernet controller: Realtek RTL8111/8168
lsmod | grep r8169
# باید r8169 بارگذاری شده باشد
modprobe r8169 # در صورت نبود۲. IP دارم اما DNS کار نمیکند
ping 8.8.8.8 # کار میکند
ping gentoo.org # خطای: Temporary failure in name resolutionراهحل:
# بررسی resolv.conf
cat /etc/resolv.conf
# اگر خالی است:
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 1.1.1.1" >> /etc/resolv.conf
# اگر NetworkManager اجرا میشود، آن را موظف کنید resolv.conf را مدیریت کند:
nmcli connection modify "Wired connection 1" ipv4.dns "8.8.8.8 1.1.1.1"
nmcli connection up "Wired connection 1"
# در systemd-resolved:
systemctl enable --now systemd-resolved
ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
resolvectl statusبرای جزئیات بیشتر به آموزش Networking مراجعه کنید.
۳. نام رابط تغییر کرده (بهجای eth0، enp3s0)
دلیل: predictable network interface names در udev/systemd است. راهحل: پیکربندی را با نام جدید بهروزرسانی کنید یا predictable naming را غیرفعال کنید:
# پیدا کردن نام واقعی
ip link show
# بهروزرسانی /etc/conf.d/net
nano /etc/conf.d/net
# config_enp3s0="dhcp"
# symlink جدید
ln -s /etc/init.d/net.lo /etc/init.d/net.enp3s0
rc-update del net.eth0 default 2>/dev/null
rc-update add net.enp3s0 default
# یا غیرفعالکردن predictable naming (بهسادگی قدیمی)
# اضافهکردن به کرنل cmdline:
# net.ifnames=0 biosdevname=0
# سپس update-grubمشکلات بستهها
۱. بسته مسدودشده (blocked)
[blocks B ] <sys-libs/zlib-1.3 ("<sys-libs/zlib-1.3" is blocking sys-libs/zlib-1.3.1)دلیل: نسخه قدیمی با نسخه جدید ناسازگار است. راهحل:
# حذف بسته مسدودکننده
emerge --ask --depclean sys-libs/zlib
# یا اجبار به نصب نسخه جدید
emerge --ask --nodeps sys-libs/zlib
# سپس @world را بهروز کنید
emerge -avuDN @world۲. بسته mask شده
!!! All ebuilds that could satisfy "x11-drivers/nvidia-drivers" have been masked.دلیل: بسته با KEYWORD یا LICENSE mask شده. راهحل:
# بررسی دلیل mask
emerge --info x11-drivers/nvidia-drivers | grep -E "KEYWORDS|LICENSE"
# در mask بهدلیل KEYWORD (مثلاً ~amd64):
echo "x11-drivers/nvidia-drivers ~amd64" >> /etc/portage/package.accept_keywords/nvidia
# در mask بهدلیل LICENSE:
echo "x11-drivers/nvidia-drivers NVIDIA-r2" >> /etc/portage/package.license/nvidia
# در mask بهدلیل hardmask (احتیاط!):
# /etc/portage/package.unmask/nvidia
# x11-drivers/nvidia-drivers::gentoohardmask بهمعنی خطر است
اگر بسته در /usr/portage/profiles/package.mask قرار دارد (نه تنها بهدلیل KEYWORD)، دلیل جدیای دارد: ناپایداری، آسیبپذیری، یا در حال توسعه بودن. تنها در صورتی که واقعاً میدانید چه میکنید، آن را unmask کنید. برای جزئیات به آموزش Portage مراجعه کنید.
۳. وابستگی چرخهای (circular dependency)
Calculating dependencies... done!
* Error: circular dependencies:
* dev-libs/libfoo-1.0 depends on dev-libs/libbar-1.0
* dev-libs/libbar-1.0 depends on dev-libs/libfoo-1.0راهحل: بهروزرسانی Portage، تغییر USE flag، یا نصب موقت با --nodeps:
# بهروزرسانی Portage
emerge --ask sys-apps/portage
# تلاش با USE flag متفاوت
USE="-foo" emerge -avuDN @world
# نصب موقت با --nodeps (احتیاط)
emerge --ask --nodeps dev-libs/libfoo
emerge --ask --nodeps dev-libs/libbar
# سپس @world را بهروز کنید
emerge -avuDN @world۴. شکست در دریافت سورس (fetch failure)
!!! dev-libs/openssl-3.2.1: fetch failed
!!! Couldn't download 'openssl-3.2.1.tar.gz'. Aborting.دلیل: سرور mirror در دسترس نیست یا فایروال مانع میشود. راهحل:
# بررسی اتصال
ping gentoo.osuosl.org
# آزمایش دستی wget
wget https://www.openssl.org/source/openssl-3.2.1.tar.gz
# تغییر mirrorها در make.conf
# GENTOO_MIRRORS="https://gentoo.osuosl.org/ https://mirror.leaseweb.com/gentoo/"
# یا بهطور موقت
GENTOO_MIRRORS="https://mirror.leaseweb.com/gentoo/" emerge --ask dev-libs/openssl
# اگر همه mirrorها شکست خوردند، فایل را دستی دانلود و در /usr/portage/distfiles بگذارید
mv openssl-3.2.1.tar.gz /var/cache/distfiles/
emerge --ask dev-libs/opensslمشکلات نمایشگر
۱. صفحه سیاه پس از بوت گرافیکی
دلیل: درایور گرافیکی نصب یا بارگذاری نشده است. راهحل: بهطور موقت به ترمینال متنی بروید (Ctrl+Alt+F2):
# بررسی لاگ Xorg
cat /var/log/Xorg.0.log | grep -E "EE|WW" | head -20
# (EE) NVIDIA: Failed to initialize the NVIDIA kernel module
# (EE) Failed to load module "nvidia" (module does not exist)
# یا Wayland
journalctl --user -u seatd -u greetd
# بررسی درایور بارگذاریشده
lsmod | grep -E "nvidia|amdgpu|i915|nouveau"
# در صورت نبود، نصب:
emerge --ask x11-drivers/nvidia-drivers # NVIDIA
modprobe nvidia
# یا برای AMD/Intel، مطمئن شوید mesa نصب است:
emerge --ask media-libs/mesa۲. رابط گرافیکی بالا نمیآید (no GUI)
# بررسی display manager
rc-service xdm status # یا systemctl status display-manager
# بررسی لاگ
journalctl -u display-manager -b
# یا
cat /var/log/Xorg.0.log | grep "EE"
# اگر Xorg اصلاً اجرا نمیشود:
emerge --ask x11-base/xorg-server x11-base/xorg-drivers
rc-update add xdm default # OpenRC
rc-service xdm start۳. عدم تطابق درایور GPU (مثلاً NVIDIA)
NVIDIA: API mismatch: the NVIDIA kernel module has version 565.77,
but this X module has version 550.135دلیل: ماژول هسته با کتابخانه userspace هماهنگ نیست. راهحل:
# بازسازی ماژول برای کرنل فعلی
emerge @module-rebuild
# یا نصب مجدد کامل nvidia-drivers
emerge --ask x11-drivers/nvidia-drivers
# اطمینان از بارگذاری ماژول جدید
rmmod nvidia nvidia_modeset nvidia_uvm nvidia_drm 2>/dev/null
modprobe nvidia
lsmod | grep nvidiaبرای جزئیات بیشتر به آموزش NVIDIA، آموزش AMD و آموزش Intel مراجعه کنید.
مشکلات صدا
۱. هیچ صدایی نمیآید
# بررسی اجرای PipeWire
pgrep -a pipewire
pgrep -a wireplumber
# اگر نبود:
systemctl --user start pipewire wireplumber pipewire-pulse
systemctl --user enable pipewire wireplumber pipewire-pulse
# بررسی گروهها
groups
# باید شامل audio و video باشد
gpasswd -a ali audio
gpasswd -a ali video
# سپس خروج و ورود مجدد
# تست
speaker-test -c2 -twav۲. pavucontrol خطا میدهد
Connection to PulseAudio failed.systemctl --user status pipewire-pulse
# اگر failed:
systemctl --user restart pipewire-pulse
# بررسی socket
ls -la /run/user/$(id -u)/pulse/nativeبرای جزئیات به آموزش PipeWire مراجعه کنید.
مشکلات دیسک
۱. دیسک پر شده
# پیدا کردن دایرکتوریهای بزرگ
du -sh /* 2>/dev/null | sort -rh | head
# 12G /var
# 8.5G /usr
# 4.2G /home
du -sh /var/* 2>/dev/null | sort -rh | head
# 5.0G /var/cache
# 3.0G /var/log
# 2.0G /var/lib/docker
# پاکسازی cache های Portage
eclean-dist # از app-portage/gentoolkit
eclean-pkg
# یا دستی
rm -rf /var/cache/distfiles/*
rm -rf /var/cache/binpkgs/*eclean برای نگهداری نسخههای اخیر
eclean-dist --destructive همهٔ فایلهای distfiles قدیمی را حذف میکند. اگر میخواهید تنها نسخههای قدیمی را حذف کنید، آن را بدون --destructive اجرا کنید تا نسخههای نصبشده نگه داشته شوند.
۲. فایلسیستم read-only شده
EXT4-fs error (device sda3): ext4_journal_check_start:83: Aborting journal
EXT4-fs (sda3): Remounting filesystem read-onlyدلیل: خطای سختافزاری دیسک یا فایلسیستم است. راهحل:
# بررسی سلامت دیسک
smartctl -a /dev/sda | grep -E "Reallocated|Pending|Offline_Uncorrectable"
# اگر خطاهای زیادی بود، دیسک در حال مرگ است — بکآپ بگیرید!
# fsck از محیط live
umount /dev/sda3 # اگر ریشه است، از Live USB بوت کنید
fsck.ext4 -f /dev/sda3
# پاسخ به سوالات (معمولاً y برای همه)
# اگر دوباره اتفاق افتاد، دیسک را عوض کنید۳. fsck هنگام بوت شکست میخورد
# بوت با init=/bin/bash یا rescue mode
# سپس:
mount -o remount,rw /
fsck -y /dev/sda3
rebootهرگز fsck روی فایلسیستم mountشده اجرا نکنید
اجرای fsck روی فایلسیستم mountشده میتواند آن را بهشدت خراب کند. همیشه ابتدا umount کنید یا از Live USB بوت کنید. اگر پارتیشن ریشه باشد و نتوان آن را umount کرد، با init=/bin/bash یا systemd.unit=rescue.target بوت کنید.
چکلیست عیبیابی سریع
| نشانه | نخستین دستور |
|---|---|
| سیستم بوت نمیشود | journalctl -b (یا dmesg از Live USB) |
| سرویس کار نمیکند | systemctl status SERVICE یا rc-service SERVICE status |
| شبکه قطع است | ip addr و ping 8.8.8.8 |
| بسته نصب نمیشود | emerge --info PACKAGE |
| صفحه سیاه | cat /var/log/Xorg.0.log | grep EE |
| صدا کار نمیکند | pgrep -a pipewire و wpctl status |
| دیسک پر | du -sh /* | sort -rh |
| خطای کرنل | dmesg | tail -50 |
| افت کارایی | top, iotop, nproc |
خلاصه و مرحله بعد
عیبیابی Gentoo با خواندن لاگ آغاز میشود: journalctl برای systemd، dmesg برای هسته و /var/log/messages برای OpenRC. برای هر دسته از مشکلات (بوت، شبکه، بسته، نمایشگر، صدا، دیسک)، یک الگوی مشخص وجود دارد: نشانه → تشخیص → راهحل. در صورت شک، همیشه به آموزش بهروزرسانی برگردید و مطمئن شوید سیستم بهروز است.
برای خطاهای بوت به آموزش GRUB و آموزش Manual Kernel مراجعه کنید. برای مشکلات شبکه به آموزش Networking، برای خطاهای بسته به آموزش Portage و برای خطاهای گرافیکی به آموزش NVIDIA، آموزش AMD یا آموزش Intel مراجعه کنید. برای مشکلات صدا نیز آموزش PipeWire را ببینید.
این صفحه در تاریخ ۱ تیر ۱۴۰۵ بهروزرسانی شده است.