Genkernel

From Gentoo Wiki
Jump to:navigation Jump to:search
This page is a translated version of the page Genkernel and the translation is 47% complete.
Other languages:
Not to be confused with gentoolkit.


Resources
Article status
This article has some todo items:
  • Article must be updated for genkernel-4 in general
  • Add documentation for --boot-font feature
  • Add documentation for --bcache feature
  • Add documentation for gk.keep feature (including /etc/initramfs.mounts)

A genkernel egy Gentoo által készített szoftvereszköz, amelyet a bináris futtatható kernel és bináris futtatható initramfs képfájlok létrehozási folyamatának automatizálására terveztek. Néhány általános jellemzője:

  • A kernel forráskódok beállítása.
  • A tömörített bináris kernelképfájl bzImage létrehozása és másolása a /boot könyvtárba.
  • Egy initramfs bináris képfájl létrehozása és másolása a /boot könyvtárba.
  • Szimbolikus linkek létrehozása a /boot könyvtárban.
  • Egyedi tartalmak hozzáadása az initramfs bináris képfájlhoz, például titkosítással kapcsolatos fájlok, indítóképernyőn megjelenő képek, extra modulok és egyebek.
  • A bootloader beállítása az újonnan létrehozott kernel és initramfs indításához.
Note
Az újabb UEFI rendszerek esetén a /boot helyett a /efi használatához tekintse meg a Changing the boot directory to /efi leírást.
Note
Gyakori tévhit, hogy a genkernel "automatikusan" létrehoz egy egyedi kernelbeállítást. A genkernel automatizálja a kernel létrehozási (felépítési) folyamatát és összeállítja a bináris initramfs képfájlt, de nem hoz létre egyedi kernelbeállítás fájlt. Ha nincs megadva kernelbeállítás, akkor a genkernel egy általános kernelbeállítás fájlt használ, amely általános célú kernelt eredményez, amely alkalmas mindennapi használatra (nagyméretű moduláris kernel árán).


Ugyanez igaz a genkernel initramfs képfájljára is: Elsődleges feladata, hogy csak az alapvető dolgokat hozza létre, amelyek szükségesek egy (blokk) eszköz felcsatolásához, amely tartalmazza a gyökérfájlrendszert, hogy a lehető leggyorsabban átadhassa az irányítást az igazi rendszernek.

Nem az a genkernel célja, hogy az összes elérhető modult betöltse, az összes elérhető eszközt elindítsa, további köteteket feloldjon, hálózatot indítson, vagy egyéb különleges dolgokat végezzen. Ezért ne felejtse el beállítani a normál indítási szolgáltatásokat, hogy a valódi rendszer be tudja fejezni az indítást, és elvégezhesse az összes fent említett feladatot.

Telepítés

USE jelölőzászlók

USE flags for sys-kernel/genkernel Gentoo automatic kernel building scripts

+firmware Prefer system firmware sys-kernel/linux-firmware over local copy.
ibm Add support for IBM ppc64 specific systems
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
Data provided by the Gentoo Package Database · Last update: 2025-04-13 21:23 More information about USE flags

Emerge

Indítsa el a genkernel telepítését:

root #emerge --ask sys-kernel/genkernel

Használat

A genkernel futtatásának az általános formája a következő:

root #genkernel [options ...] action

Opciók

A genkernel tényleges működése számos különféle beállítástól függ, amelyek többsége a /etc/genkernel.conf fájlban állítható be vagy törölhető, vagy a genkernel parancs segítségével minden meghívás során megadható. A parancssoron keresztül megadott opciók elsőbbséget élveznek a /etc/genkernel.conf fájlban meghatározott opciókkal szemben. A beállításfájl rendkívül jól dokumentált, azonban a leggyakrabban használt opciók közül néhányat ebben a cikkben tárgyalunk. A cél az, hogy az olvasó megismerje a gyakori genkernel meghívásokat. A teljesebb magyarázatok érdekében tekintse meg a /etc/genkernel.conf fájlban található megjegyzéseket vagy a man genkernel kimenetét.

Note
Néhány opció rendelkezik egy változattal, amely ellentétes működést vált ki, és --[no-]option_name formában van feltüntetve, az ellentétes hatás pedig szögletes zárójelben jelenik meg, az alábbi példában:
CODE Egy bizonyos opció engedélyezése vagy letiltása
--[no-]menuconfig : Activates [deactivates] ...
Azoknál az opcióknál, amelyeknek csak negatív hatásuk van, a no- és annak hatása (amely ebben az esetben nem opcionális) szögletes zárójelek nélkül van feltüntetve.

Opciók hatása a felhasználói interakcióra

Az alább felsorolt beállítási lehetőségek segítenek a felhasználónak eldönteni, hogy miként lépjen kapcsolatba a beállítási folyamattal. A felhasználók még azt is eldönthetik, hogy a folyamat során létrehozott beállításfájlt el kell-e menteni. Az alábbiak elsődleges beállítási lehetőségeknek számítanak:

--config=/path/to/genkernel.conf
A genkernel beállításfájljára mutat, amelyet használni kell (alapértelmezés szerint: /etc/genkernel.conf).
--kernel-config=/path/to/kernel.config
A használni kívánt kernelbeállítás fájlra mutat. Az aktuálisan futó kernel beállításának újrahasználatához megadható a /proc/config.gz, ha létezik. Alapértelmezés szerint a genkernel az előzőleg létrehozott ugyanazon kernelverzió beállítását használja, vagy ha nincs előző beállítás, akkor egy alapértelmezett kernelbeállítást használ. A default speciális érték használatával kényszeríthető a genkernel általános kernelbeállításának a használata. Ez a hely nem lehet /usr/src/linux/.config, mivel elveszhet, vagy hibákat okozhat.
--[no-]menuconfig
Aktiválja (vagy deaktiválja) a make menuconfig parancsot (amely egy interaktív beállításmenüt hív elő), mielőtt a bináris kernelképfájl létrehozása megkezdődne.
--gconfig
Egy kernelbeállítási eszközt biztosít, amely a GTK könyvtáraktól függ. Az előnye ennek az opciónak, hogy a legtöbb felhasználó könnyebbnek és érthetőbbnek találja a kernel beállítását ezen eszköz használatával, mivel az az X-ablakrendszerre támaszkodik. Az hátránya ennek az opciónak, hogy az X-ablakrendszer szükséges a használatához, tehát parancssorban nem működik.
--xconfig
Egy kernelbeállítási eszközt biztosít, amely a QT könyvtáraktól függ. Az előnye ennek az opciónak, hogy a legtöbb felhasználó könnyebbnek és érthetőbbnek találja a kernel beállítását ezen eszköz használatával, mivel az az X-ablakrendszerre támaszkodik. Az hátránya ennek az opciónak, hogy az X-ablakrendszer szükséges a használatához, tehát parancssorban nem működik.
--[no-]save-config
Elmenti [vagy nem menti el] a kernel beállítását egy fájlba a /etc/kernels könyvtárban későbbi használatra.
--kernel-append-localversion=-mycfg42
Lehetővé teszi a kernel LOCALVERSION értékének módosítását, amely hatással lesz a kernel és az initramfs fájlnevére a /boot könyvtárban, valamint a modulokra a /lib/modules/ könyvtárban. Ez különösen hasznos egy új, önálló revízió létrehozásához, saját kernel binárissal, initramfs fájlal és modulokkal. A fentebbi példa alapján, a =sys-kernel/gentoo-sources-5.4.2 esetén a amd64 architektúrával és alapértelmezett beállításokkal a következőket hozná létre: /boot/vmlinuz-5.4.2-gentoo-x86_64-mycfg42, /boot/initramfs-5.4.2-gentoo-x86_64-mycfg42.img és /lib/modules/4.19.88-gentoo-x86_64-mycfg42.

Opciók hatása a létrejövő rendszerre

Az itt felsorolt beállítási lehetőségek meghatározzák, hogy a létrejövő bináris kernelképfájlban és initrd/initramfs bináris képfájlban mely funkciók lesznek engedélyezve vagy tiltva.

--[no-]splash
Aktiválja (vagy deaktiválja) a Fbsplash framebuffer splash támogatását a genkernel által létrehozott initrd bináris képfájlon. Az fbsplash által használt alapértelmezett téma felülbírálásához használja a --splash=PreferredTheme opciót (ahol a PreferredTheme a /etc/splash könyvtáron belüli egyik könyvtár neve).
--splash-res=PreferredResolution
Ez az opció lehetővé teszi annak kiválasztását, hogy mely indítóképernyő-felbontások legyenek támogatottak az initrd bináris képfájlban a rendszer indításakor. Ez két okból hasznos. Először is, lehetőség nyílik csak a rendszerhez kapcsolódó indítóképernyő-felbontások kiválasztására. Másodszor, elkerülhető az initrd által igényelt lemezterület felesleges növekedése (mivel az initrd fájlnak nem kell támogatnia a rendszer beállításához nem releváns felbontásokat). Azonban ezt az opciót célszerű elhagyni, ha a kernelt telepítő CD lemezhez állítják össze, mivel ez lehetővé teszi az indítóképernyő minden lehetséges felbontásának támogatását.
--do-keymap-auto
Kényszeríti a billentyűzetkiosztás kiválasztását az indítási folyamat során.
--keymap
Aktiválja a billentyűzetkiosztás kiválasztását indításkor (például LUKS konténer jelszó megadásához). A kívánt billentyűzetkiosztás az indítási opciókban adható meg keymap értékeként (a billentyűzetkiosztás fájl neve ".map" nélkül). Az elérhető billentyűzetkiosztási fájlok megtalálhatók a /usr/share/genkernel/defaults/keymaps/ könyvtárban.
Ha egy szükséges billentyűzetkiosztás nem érhető el a genkernelben, akkor lehetőség van az egyik meglévő sys-apps/kbd billentyűzetkiosztás (ami a /usr/share/genkernel/defaults/keymaps/ elérhető) konvertálására a loadkeys --bkeymap parancs segítségével. További részletekért tekintse meg a loadkeys man súgóját.
--lvm
Tartalmazza az adathordozó támogatást a Logical Volume Management (LVM2) számára statikus bináris fájlok segítségével, ha az elérhető a rendszeren. Ha nem állnak rendelkezésre releváns (statikus) LVM2 bináris fájlok, akkor azok le lesznek fordítva. Az opció engedélyezése előtt győződjön meg arról, hogy telepítve van a sys-fs/lvm2 szoftvercsomag az operációs rendszeren (emerge sys-fs/lvm2), majd tekintse át a Gentoo wiki LVM cikkét.
--dmraid
Tartalmazza a DMRAID támogatását, az eszközt, amely RAID leképezéseket hoz létre a kernel eszköz-leképezési alrendszer segítségével. A DMRAID felismeri, aktiválja, deaktiválja és megjeleníti a szoftver RAID készletek (például ATARAID) és a bennük található DOS partíciók tulajdonságait.
--luks
Tartalmazza a Linux Unified Key Setup vagy LUKS támogatását. Ez lehetővé teszi egy olyan adathordozó használatát, amelyet LUKS titkosított, és amely tartalmazza a root fájlrendszert. A bootloadernél a titkosított adathordozót állítsa be crypt_root értékeként, míg a root az a nem titkosított adathordozó lesz, amelyet a LUKS létrehoz (például: /dev/mapper/root lesz a felcsatolandó útvonal, és a helyes bootloader paraméterek sora így nézhet ki: GRUB_CMDLINE_LINUX="... crypt_root=UUID=<crypto_LUKS uuid> root=/dev/mapper/root ...").
--iscsi
iSCSI támogatást ad az initrd bináris képfájlhoz.
--multipath
Multipath támogatást ad az initrd bináris képfájlhoz.
--linuxrc=/path/to/the/linuxrc_file
Megad egy felhasználó által létrehozott linuxrc-t — egy olyan szkriptet, amely a kernel indítási szakaszában inicializálódik, az aktuális boot folyamat előtt. Egy alapértelmezett linuxrc szkript megtalálható a /usr/share/genkernel/ könyvtárban. Ez a szkript lehetővé teszi egy kis, modularizált kernel indítását, megpróbálja betölteni a rendszer számára szükséges legkevesebb mennyiségű illesztőprogramot (kernelmodulok formájában).
--cachedir=/path/to/alt/dir
Felülírja az alapértelmezett gyorsítótár helyét a kernel forráskódjának a bináris kódra történő fordítása közben.
--tmpdir=/path/to/new/tempdir
Megadja annak az ideiglenes könyvtárnak a helyét, amelyet a genkernel a kernel forráskódjának a fordítása közben használ.
--unionfs
Támogatást nyújt a Unification File System számára az initrd bináris képfájlon belül.
--mountboot
Érzékeli, hogy a /boot könyvtárat külön partícióra kell-e felcsatolni. Ellenőrzi az /etc/fstab szkriptet, hogy hogyan kell (ha szükséges) a boot partíciót a fájlrendszerre felcsatolni.
--microcode
Létrehoz egy korai cpio fájlt, amely Intel/AMD processzorok mikrokódját tartalmazza a Xen és a Linux korai mikrokód támogatásához.

Létrehozáshoz használt eszközök kiválasztására ható opciók

A következő opciókat a genkernel támogatja, és a bináris kernelképfájl létrehozása közben továbbítja a releváns alkalmazásoknak. Ezek az opciók hatással vannak az alacsony szintű kernelfordító eszközökre.

--kernel-cc=someCompiler
Meghatározza a kernel forráskódjának fordítási folyamatában használt fordítót.
--kernel-ld=someLinker
Meghatározza a kernel forráskódjának fordítási folyamatában használt linkert.
--kernel-as=someAssembler
Meghatározza a kernel forráskódjának fordítási folyamatában használt assembler programot.
--kernel-make=someMake
Meghatároz egy alternatívát a GNU make segédprogramhoz, amelyet a kernel forráskódjának a fordítása során használnak.
--utils-cc=someCompiler
Meghatározza a segédprogramok forráskódjának fordítása során használt fordítót.
--utils-ld=someLinker
Meghatározza a segédprogramok forráskódjának fordítása során használt linkert.
--utils-as=someAssembler
Meghatározza a segédprogramok forráskódjának fordítása során használt assembler programot.
--utils-make=someMake
Meghatároz egy alternatívát a GNU make segédprogramhoz, amelyet a segédprogramok forráskódjának fordítása során használnak.
--makeopts=-jX
Meghatározza a párhuzamos szálak számát, amelyeket a make segédprogram alkalmazhat a kernel (és segédprogramok) forráskódjának fordítása során. Az X változó egy szabadon választott szám, bár a leggyakoribb értékeket a rendszer által használt processzormagok számához egyet (1) hozzáadva kapjuk, vagy egyszerűen a rendszer processzormagjainak számát használjuk. Például egy egy processzormagos rendszer esetén a leggyakoribb opció értékek -j2 vagy -j1, két processzormagos rendszer esetén pedig -j3 vagy -j2 opciókat alkalmazunk stb. (Egy processzorral rendelkező rendszer, amely támogatja a Hyper-Threading™ (HT) technológiát, feltételezhetően 2 maggal rendelkezik, feltéve, hogy a Symmetric Multi-Processing (SMP) támogatás engedélyezve van a kernelben.)

Forráskód kódfordítási folyamatára ható opciók

A következő opciók általában a tényleges fordítás során lépnek érvénybe:

--kerneldir=/path/to/sources/
Megad egy alternatív kernelforráskód helyet, eltérően az alapértelmezett /usr/src/linux/ helytől.
--kernel-config=/path/to/config-file
Meghatározza, hogy mely kernelbeállítást kell használni. Alapértelmezés szerint a genkernel megállapítja a kernel verzióját, amelyet a --kerneldir jelöl meg, és megkeresi a kernelbeállítást (KV) a /etc/kernels/kernel-config-$KV helyen. Ha nem található kernelbeállítás, akkor a genkernel egy általános kernelbeállítást keres a /usr/share/genkernel/$ARCH helyen. Egy speciális default érték használható arra, hogy kényszerítse a genkernel általános kernelbeállításának a használatát.
Tip
Használja a --kernel-config=/proc/config.gz opciót egy új kernel létrehozásának a megkezdéséhez az aktuálisan futó kernel kernelbeállítása alapján.
Megjegyzés: Ez csak akkor működik, ha az aktuálisan aktív kernel CONFIG_IKCONFIG=y beállítással lett létrehozva, amely általában így van.
--module-prefix=/path/to/prefix-directory/
Meghatároz egy előtagot ahhoz a könyvtárhoz, ahová a kernelmodulok telepítve lesznek (alapértelmezett útvonal a /lib/modules könyvtár).
--[no-]clean
Aktiválja (vagy deaktiválja) a make clean parancsot a kernel forráskódjának a kódfordítása előtt. A make clean parancs eltávolítja az összes objektumfájlt és szoftverfüggőséget a kernel forrásfájlfájából.
--[no-]mrproper
Aktiválja (vagy deaktiválja) a make mrproper parancsot a kernel fordítása előtt. Az előzőleg említett make clean parancshoz hasonlóan a make mrproper eltávolítja az összes objektumfájlt és szoftverfüggőséget a kernel forrásfájlfájából. Azonban minden korábbi beállításfájl (a /path/to/sources/.config vagy a /path/to/sources/.config.old helyen) is törlésre kerül a kernel forrásfájlfájából. Ha nem kívánatos, hogy a kernel .config fájlja folyamatosan eltűnjön, akkor feltétlenül tiltsa le ezt az opciót!
--oldconfig
Kiadja a make oldconfig parancsot, amely megkísérli összegyűjteni a rendszer architektúrájának beállítási információit egy általános szkripttől a /usr/share/genkernel helyről. Ez egy nem interaktív folyamat, a felhasználótól nem fogad bemenetet. Továbbá, ha a --oldconfig opciót a --clean opcióval együtt használják, akkor az utóbbi opció érvénytelenítve lesz, és aktiválódik a --no-clean opció.
--[no-]module-rebuild
Futtatja, vagy nem futtatja az emerge @module-rebuild parancsot annak érdekében, hogy a kernel és a kernelmodulok elkészülte után külső modulokat hozzon létre. Ez az opció alapértelmezés szerint engedélyezve van.
--callback="echo hello"
Meghívja a megadott argumentumokat (jelen esetben echo hello), miután a kernel és a releváns kernelmodulok létrejönnek, de még az initramfs képfájl létrejötte előtt.
Note
A genkernel-4 előtt ezt a visszahívást külső modulok újbóli létrehozásának a kiváltására használták. A genkernel-4 óta egy dedikált parancssori paramétert, a --module-rebuild opciót vezették be. Részletek fentebb.
--[no-]install
Aktiválja (vagy deaktiválja) a make install parancsot, amely telepíti az új kernelképfájlt, beállításfájlt, initrd képfájlt és rendszerleképezést a boot partícióra. Minden lefordított modul is telepítésre kerül. Alapértelmezés szerint a genkernel megkísérli felcsatolni a /boot partíciót, ha az külön partíción van, mielőtt futtatná a telepítési parancsot.
--no-ramdisk-modules
Tartózkodik attól, hogy bármilyen kernelmodult másoljon a genkernel által létrehozott initrd képfájlra. Ez az opció kivételt képez a no- előtag szabálya alól. Ennek az előtagnak az elhagyása érvénytelen genkernel opciót eredményez.
--all-ramdisk-modules
Az összes elérhető kernelmodult lemásolja a genkernel által létrehozott initrd képfájlra.
--genzimage
Létrehozza az initrd képfájlt, a kernel képfájl előtt (ez a hack jelenleg csak PPC Pegasos rendszerekre vonatkozik).

Hibakeresési opciók

A kernel kódfordítási folyamat során használt hibakeresési opciók szabályozzák a jelentett információ mennyiségét, valamint az említett adatok bemutatását.

--loglevel=<0|1|2|3|4|5>
Szabályozza a genkernel által nyomtatott információk részletességi szintjét. A LOGLEVEL változó egy 0 és 5 közötti egész szám. A '0' szint minimális kimenetet jelent (=nincs kimenet), míg az '5' a lehető legtöbb információt biztosítja a genkernel tevékenységeiről a kernel kódfordítási és az initramfs képfájl létrehozási folyamat során.
Note
A genkernel alapértelmezés szerint mindig teljes kimenetet naplóz a /var/log/genkernel.log fájlba. A --loglevel csak a képernyőn megjelenő kimenetet szabályozza.
--logfile=/path/to/output_file
Naplófájl, ahová a genkernel alapértelmezés szerint kimenetet ír. Alapértelmezett érték: /var/log/genkernel.log.
--[no-]color
Aktiválja (vagy deaktiválja) a színes kimenetet.
--[no-]cleanup
Aktiválja (vagy deaktiválja) a teljes futás utáni takarítást hibakeresési célokra.

Műveletek

A parancssoron keresztül megadott művelet a genkernel [options …] action segítségével megadja, hogy a genkernel milyen műveletet hajtson végre. A következő műveletek támogatottak:

Művelet Leírás
all Létrehozza az összes szakaszt. Initrd bináris képfájlt, a bináris kernelképfájlt és a bináris kernelmodulokat.
bzImage Kizárólag a bináris kernelképfájlt hozza létre.
kernel Kizárólag a kernelképfájlt és a modulokat hozza létre.
initramfs Kizárólag az initramfs/ramdisk bináris képfájlt hozza létre.
ramdisk Kizárólag az initramfs/ramdisk bináris képfájlt hozza létre.

Beállítás

Kezdeti lépések

Bár több módja van a genkernel futtatásának, a legtöbb felhasználó számára ajánlott legkevésbé invazív megközelítést a genkernel all biztosítja. Ebben az esetben egy általános beállítást használnak, amely a legtöbb rendszerben jól működik. Mint korábban említettük, ez a megközelítés nem mentes a hátrányoktól, így az elkészített modulok többsége haszontalan az átlagfelhasználó számára, és növelheti a kódfordítási időt. Az alábbiakban bemutatjuk egy hatékonyabb megközelítést, amelyet bizonyos opciók root jogosultságú genkernel számára való átadásával érhetünk el:

root #genkernel --luks --no-install --no-clean --menuconfig all

A fenti művelet eredményeként a genkernel létrehoz egy kernelt, amely képes megnyitni LUKS és LUKS2 titkosított köteteket, lefordítja és beágyazza a cryptsetup szoftvert az initramfs bináris képfájlba (--luks), és mind a kernelképfájlt, mind az initramfs képfájlt manuálisan kell telepíteni (--no-install). A kernel forráskódfájlfájának előkészítése során a genkernel tartózkodik attól, hogy kitisztítson bármilyen előzetesen meglévő objektumfájlt a forráskódfájlban (--no-clean). Egy menü vezérelt kernel-beállító eszköz fog megjelenni, amely lehetővé teszi a felhasználó számára, hogy kiválassza, mely kernelmodulok jöjjenek létre a rendszer számára (--menuconfig).

Ha a --symlink opció meg van adva, akkor a --no-install opció --install opcióval történő helyettesítése lehetővé teszi a genkernel számára, hogy automatikusan telepítse az új kernelt a /boot könyvtárba, és szimbolikus linkeket hozzon létre. A --mountboot opció használatával a genkernel automatikusan felcsatolhatja a /boot partíciót, amennyiben ez szükséges.

Note
Ne felejtse el, hogy a /etc/genkernel.conf fájlt a genkernel parancs induláskor beolvassa, és minden ott meghatározott opció alkalmazásra kerül, kivéve, ha egy parancssori opció elsőbbséget élvez vele szemben.

Boot könyvtár megváltoztatása /efi könyvtárra

Most ajánlott az UEFI rendszer boot partíciót (ESP) a /efi alá csatolni a /boot helyett.

Alapértelmezés szerint a kernel a /boot könyvtárba kerül, amely bizonyos beállításokban korábban az ESP volt, de most a gyökérpartíción található. Az okok, amelyek miatt érdemes a kernelt a /efi könyvtárba írni, a következők lehetnek:

  • A Secure Boot egy előre megadott ESP kernel útvonalat vár el.
  • A GRUB2 függetlenné tétele a gyökérpartíciótól a stabilitás vagy biztonság érdekében.
  • A GRUB2 nem támogatja a gyökérfájlrendszert (bcachefs).
  • A grub-mkconfig által nem generált grub.cfg használata.


A genkernel a /efi helyre való mutatásához adja hozzá a --bootdir=/efi opciót a genkernel parancshoz, vagy a BOOTDIR="/efi" beállítást a /etc/genkernel.conf fájlhoz.

FILE /etc/genkernel.confBoot könyvtár megváltoztatása /efi könyvtárra az /etc/genkernel.conf fájlban
# Állítsa be a boot könyvtárat. Alapértelmezett érték a /boot könyvtár.
BOOTDIR="/efi"

Kernel módosítása

Az első lépés az, hogy engedélyezze a make menuconfig indítását az /etc/genkernel.conf fájlban:

FILE /etc/genkernel.conf"Beállításmenü használatának kényszerítése az /etc/genkernel.conf fájlban
# Fut-e a 'make menuconfig', mielőtt lefordítja ezt a kernelt?"
MENUCONFIG="yes"

Fájlkezelés

A genkernel használata során a felhasználónak tisztában kell lennie a kernel beállítással és a bináris kernelképfájlok kezelésével kapcsolatos néhány szemponttal, valamint azzal, hogy miként kezeli a rendszer a kernelforráskódokat.

Forráskód fájlok

A emerge -u gentoo-sources parancs kiadása után egy könyvtár jön létre a /usr/src/ alatt az új források tárolására. Általában az aktív kernel forráskönyvtárra a /usr/src/linux szimbolikus link mutat.

A /usr/src könyvtár például így nézhet ki:

user $ls -l /usr/src
total 24
drwxr-xr-x  6 root root 4096 Dec 16 00:56 .
drwxr-xr-x 12 root root 4096 Dec 15 12:42 ..
-rw-r--r--  1 root root    0 Mar 19  2015 .keep
lrwxrwxrwx  1 root root   22 Dec 16 00:56 linux -> linux-5.3.14-gentoo-r1
drwxr-xr-x 26 root root 4096 Nov 24 03:33 linux-4.19.85-gentoo
drwxr-xr-x 27 root root 4096 Dec  9 15:10 linux-4.19.88-gentoo
drwxr-xr-x 27 root root 4096 Dec 16 00:51 linux-4.19.89-gentoo
drwxr-xr-x 25 root root 4096 Dec 16 00:58 linux-5.3.14-gentoo-r1

A /usr/src/linux szimbolikus linket többféleképpen lehet megváltoztatni.

  • Ha a symlink USE jelölőzászló engedélyezve van, akkor a /usr/src/linux szimbolikus link automatikusan frissül, hogy az újonnan letöltött forráskódokra mutasson.
  • Ha a symlink USE jelölőzászló nincs engedélyezve, akkor a felhasználó megváltoztathatja a szimbolikus link célpontját az eselect kernel list, majd az eselect kernel set parancs használatával.

A genkernel mindig (kizárólagosan) a /usr/src/linux szimbolikus link által megadott forráskódokat fogja használni.

Kernel beállításfájl

Ha már lefutott egy kernel forráskód fordítás az aktív kernel forráskódokkal, akkor előfordulhat, hogy az /etc/kernels könyvtárban található egy fájl, amely tartalmazza azt a kernelbeállítást, amelyet az utolsó kernel bzImage létrehozásakor alkalmaztak. Ez a fájl például a következő néven szerepelhet: kernel-config-5.3.14-gentoo-r1-x86_64-wifitest2, ahol a x86_64 helyére a rendszer architektúrája kerülhet, a 5.3.14-gentoo-r1 helyére a használt források szoftvercsomag/verziója, a wifitest2 helyére pedig a LOCALVERSION felhasználó által hozzáfűzött értéke kerülhet.

Ez a kernel-config-5.3.14-gentoo-r1-x86_64-wifitest2 fájl szolgál kiinduló beállításként a  genkernel --menuconfig all futtatásakor.

Ha először futtatja a genkernel szoftvert az új kernel forráskódokkal, vagy ha az előző eredményt nem mentette el, akkor ezt a fájlt egy alapértelmezett beállításfájl helyettesíti, amely a usr/share/genkernel/arch/x86_64/generated-config könyvtárban található, ahol az x86_64 helyébe az aktuális architektúra lép.

Note
Az alapértelmezett beállításfájl elérési útja módosítható a DEFAULT_KERNEL_CONFIG változó beállításával az /etc/genkernel.conf fájlban.
Lefordított beállítás mentése

Ha a --save-config genkernel opció aktiválva van, akár a parancssorból, akár az /etc/genkernel.conf fájlban, akkor a lefordított kernel beállítás elmentésre kerül (a fent megadott néven) az /etc/kernels könyvtárba. Ugyanakkor a beállítás mentésre kerül a .config fájlba az /usr/src/linux könyvtárban, de ezt a fájlt nem lesz újra felhasználva a következő genkernel all futtatásakor.

Warning
Fontos tudni, hogy minden alkalommal, amikor a genkernel futtatásra kerül a --save-config opcióval, az /etc/kernels könyvtárban lévő beállításfájl felülíródik. Ezért erősen ajánlott ezt a fájlt egy új név alatt lemásolni mielőtt a genkernel futtatásra kerül, hogy megőrizhető legyen.
Kernel és az initramfs bináris képfájlok telepítése a /boot könyvtárba

A --install opció megadásával a genkernel parancs futtatásakor a genkernel telepíti a bináris kernelképfájlt és az bináris initramfs képfájlt a /boot könyvtárba. Az --install kényelmes használatához állítsa be a következőt az /etc/genkernel.conf fájlban:

FILE /etc/genkernel.conf"Kernel és az initramfs automatikus mentésének beállítása
# BOOTDIR automatikus felcsatolása, ha az még nincs felcsatolva.
MOUNTBOOT="yes"
  
# Mentse el az új konfigurációt az /etc/kernels könyvtárba
# a fordítás sikeres befejezése után.
SAVE_CONFIG="yes"
  
# Készítsen szimbolikus linkeket a BOOTDIR-ben automatikusan.
SYMLINK="yes"
  
# Új kernel hozzáadása a grub bootloaderhez:
# Lehetséges értékek: empty/"no", "grub", "grub2"
BOOTLOADER="grub2"
  • Az első paraméter önmagáért beszél.
  • A második paraméter azt mondja meg a genkernel számára, hogy mentse el a lefordított kernelbeállítást az /etc/kernels könyvtárba.
  • Az utolsó két opció arra utasítja a genkernel szoftvert, hogy automatikusan frissítse a grub beállítását. Gyakorlatban a következők történnek:
    • Ha egy előző bináris kernelképfájl ugyanazzal a névvel már létezik, akkor a neve kiegészül a .old utótaggal. Ezzel egyidőben automatikusan létrejön egy kernel.old szimbolikus link, amely erre a régi kernel bináris képfájlra mutat.
    • Az új bináris kernelképfájl a /boot könyvtárban átveszi bármelyik, ugyanazzal a névvel rendelkező bináris kernelképfájl helyét. Ha ez az első alkalom, hogy egy kernel lefordításra kerül, akkor automatikusan létrejön egy szimbolikus link, amely az új bináris kernelképfájlra mutat.

A genkernel --menuconfig all futtatása után a /boot könyvtár például így nézhet ki:

user $ls -al /boot
total 69388
lrwxrwxrwx 1 root root      44 Dec 16 00:58 System.map -> System.map-5.3.14-gentoo-r1-x86_64-wifitest2
-rw-r--r-- 1 root root 3465443 Dec  9 15:05 System.map-4.19.88-gentoo-x86_64
-rw-r--r-- 1 root root 3465554 Dec 16 00:45 System.map-4.19.89-gentoo-x86_64
-rw-r--r-- 1 root root 3645309 Dec 15 16:07 System.map-5.3.14-gentoo-r1-x86_64
-rw-r--r-- 1 root root 3645309 Dec 15 16:07 System.map-5.3.14-gentoo-r1-x86_64.old
-rw-r--r-- 1 root root 3645309 Dec 16 00:58 System.map-5.3.14-gentoo-r1-x86_64-wifitest2
drwxr-xr-x 2 root root    4096 Mar 21  2015 efi
drwxr-xr-x 6 root root    4096 Dec 16 01:02 grub
lrwxrwxrwx 1 root root      47 Dec 16 01:02 initramfs -> initramfs-5.3.14-gentoo-r1-x86_64-wifitest2.img
-rw-r--r-- 1 root root 3631084 Dec  9 15:34 initramfs-4.19.88-gentoo-x86_64.img
-rw-r--r-- 1 root root 3637148 Dec 16 00:54 initramfs-4.19.89-gentoo-x86_64.img
-rw-r--r-- 1 root root 3670176 Dec 15 17:41 initramfs-5.3.14-gentoo-r1-x86_64.img
-rw-r--r-- 1 root root 3669692 Dec 16 01:02 initramfs-5.3.14-gentoo-r1-x86_64-wifitest2.img
-rw-r--r-- 1 root root  168960 Nov 16 19:10 intel-uc.img
lrwxrwxrwx 1 root root      41 Dec 16 00:58 kernel -> vmlinuz-5.3.14-gentoo-r1-x86_64-wifitest2
-rw-r--r-- 1 root root 7509552 Dec  9 15:05 vmlinuz-4.19.88-gentoo-x86_64
-rw-r--r-- 1 root root 7509552 Dec 16 00:45 vmlinuz-4.19.89-gentoo-x86_64
-rw-r--r-- 1 root root 7784496 Dec 15 16:07 vmlinuz-5.3.14-gentoo-r1-x86_64
-rw-r--r-- 1 root root 7784496 Dec 15 16:07 vmlinuz-5.3.14-gentoo-r1-x86_64.old
-rw-r--r-- 1 root root 7784496 Dec 16 00:58 vmlinuz-5.3.14-gentoo-r1-x86_64-wifitest2

Rendszerbetöltő (bootloader) beállítása

extlinux

TODO

GRUB Legacy
Warning
A következő szöveg a GRUB Legacy bootloaderről szól, amelyet 2019 februárjában eltávolítottak a Gentoo-ból. Ha csak lehetséges akkor kérjük, hogy migráljon a GRUB2 bootloaderre a lehető leghamarabb.

A bootloader beállításában bemutatott szimbolikus linkek használhatók arra, hogy még ha az új bináris kernelképfájl nem is indítható, akkor is a felhasználó még mindig elindíthatja az operációs rendszert a régi bináris kernelképfájl segítségével.

Annak érdekében, hogy a genkernel által biztosított kernel és initrd megfelelően működjön, adja meg a minimum információkat a rendszerbetöltő (bootloader) beállításfájljában:

  • Adja hozzá a root=/dev/sdaN paramétert a kernelképfájlhoz továbbított kernelparaméterekhez, ahol a /dev/sdaN az gyökérpartícióra (root partícióra) mutat (az N az adott partíció számát jelöli, ha létezik partíció).
  • Ha használ splash-t, akkor adjon hozzá egy megfelelő módvonalat, például vga=0x317 a kernelhez továbbított paraméterekhez, és szintén adja hozzá a splash=verbose vagy splash=silent lehetőséget attól függően, hogy mennyi részletességet szeretne az boot folyamat során.
  • Adja hozzá az initrd információkat a bootloader igénye szerint. A részletekről, hogy miként teheti initrd-kompatibilissé a bootloadert, tekintse meg a Gentoo kézikönyv Bootloader beállítása fejezetét.

Íme, így nézhet ki a grub.conf fájl.

FILE /boot/grub/grub.confPélda a grub.conf fájlra
# This is a sample grub.conf for use with Genkernel, per the Gentoo handbook 
# http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=10#doc_chap2
# When not using Genkernel, see the handbook.
# Alternatively, see grub.conf.sample in the GRUB documentation.
  
default 0 
timeout 5
splashimage=(hd1,0)/boot/grub/splash.xpm.gz 
   
title Gentoo Linux 
root (hd0,6) 
kernel /boot/kernel initrd=/dev/ram0 root=/dev/sda7 rootfstype=ext4  
initrd /boot/initramfs
  
title Gentoo Linux old kernel 
root (hd0,6) 
kernel /boot/kernel.old initrd=/dev/ram0 root=/dev/sda7 rootfstype=ext4 
initrd /boot/initramfs.old
GRUB

TODO

systemd-boot

TODO

Munkafájlok megőrzése

A genkernel alkalmazás automatikusan menti a fájlokhoz végzett új módosításokat. Ha a korábbi módosításokat meg kell őrizni, akkor a következő lépéseket kell elvégezni.

  • Az első megőrzendő fájl a kernel beállításfájl, amely a /etc/kernels/ elérési útvonalon található. Ha a forrás nem változott meg a kernel újrafordítása előtt, akkor a korábban használt név lesz alkalmazni ehhez a fájlhoz. Ezért az előző beállításfájl másik néven történő másolása segít megőrizni az információkat, miközben a fájl új beállítási kiindulópontjaként is elérhető marad.
  • A második fontos dolog a már bootolható bináris kernelképfájl és bináris initramfs képfájlok megőrzése. Ennek megvalósítása a környezettől függ:
  1. Ha az utolsó lefordított kernel bootolható, akkor a genkernel futtatásakor ez a kernel (és hasonlóan az initramfs) képfájl át lesz nevezve vmlinuz-$KV.old névre, és létrejön egy új vmlinux-$KV bináris képfájl. Ez azt jelenti, hogy még akkor is, ha az új kernel nem bootolható, akkor is a felhasználók mindig képesek lesznek a régi kernel bootolására.
  2. Ha az utolsó lefordított kernel nem bootolható, és a forráskódok nem változtak meg azóta, hogy a felhasználó egy bootolható kerneltképfájlt elkészített, akkor a genkernel futtatása előtt először törölje az új kernelképfájlt, és távolítsa el a .old utótagot az utolsó bootolható bináris kernelképfájl nevéből. Enélkül, ha az újonnan fordított kernelképfájl másodjára sem bootolható, akkor a bootolható vmlinuz-$KV.old fájl törlésre kerül a nem bootolható vmlinuz-$KV képfájl átnevezése miatt, ami a felhasználónak egy bootolhatatlan rendszert eredményezhet. Ugyanezt az elvet alkalmazza az initramfs képfájl esetében is.
Note
A genkernel-4 óta ajánlott új, független verziókat létrehozni, mindegyikhez saját bináris kernelképfájllal használva, bináris initramfs képfájllal és a /lib/modules könyvtárban telepített kernelmodulokkal a genkernel --kernel-append-localversion=-my-new-revision all parancs használatával.

Korábbi kernelbeállítás használata a forráskódok módosítása közben

A korábbi beállítás a /etc/genkernel.conf fájlban található MENUCONFIG változón keresztül használható az alábbiak szerint:

FILE /etc/genkernel.confA make menuconfig beállítása
# Futtassa a 'make menuconfig' parancsot a kernel kódfordítása előtt.
MENUCONFIG="yes"
Note
Nincs szükség manuálisan futtatni a make oldconfig parancsot a genkernel használatakor, még akkor sem, ha a forráskódok megváltoztak. Ennek oka, hogy a make menuconfig megpróbálja a lehető legnagyobb mértékben betölteni az előző beállítást a menübe. Mindazonáltal ajánlott gondosan áttekinteni minden lehetőséget és az új szakaszokat.

Annak ellenőrzése, hogy az initramfs tartalmazza-e a szükséges modulokat/eszközöket az indítás előtt

Az bootolás előtt érdemes lehet ellenőrizni, hogy az initramfs bináris képfájl tartalmazza-e a szükséges eszközöket és modulokat. Például, ha távoli feloldási képességeket kíván használni egy képernyő nélküli operációs rendszeren a LUKS segítségével, akkor győződjön meg arról, hogy a hálózati interfészkártya, a dropbear és a cryptsetup kernelmoduljai bekerültek a bináris képfájlba.

Az lsinitrd használata

A genkernel-4 óta a létrehozott initramfs bináris képfájlok feldolgozhatóak a sys-kernel/dracut szoftvercsomagból származó lsinitrd parancs segítségével:

user $lsinitrd /boot/initramfs-5.3.14-gentoo-r1-x86_64-wifitest2.img

A fenti kimenet azt mutatja, hogy a e1000.ko kernelmodulfájl egy Intel NIC számára, a dropbear végrehajtható fájl (usr/bin/dropbearmulti), és a cryptsetup végrehajtható fájl (sbin/cryptsetup) bekerült az initramfs bináris képfájlba.

Manuális kicsomagolás

A létrehozott bináris initramfs képfájl kicsomagolásához és tartalmának ellenőrzéséhez futtassa:

root #mkdir /tmp/initramfs
root #cd /tmp/initramfs
root #xzcat /boot/initramfs-5.3.14-gentoo-r1-x86_64-wifitest2.img | cpio -idmv
root #ls -l sbin/cryptsetup 
-rwxr-xr-x   1 root     root      2813384  Dec 16 01:49 sbin/cryptsetup
Note
A manuális kicsomagolás nehézkes lehet, ha a CPU mikrokódfrissítések beépültek az initramfs bináris képfájlba.

Mikrokód betöltése

For microcode (ucode) updates, kernel must support (early-)microcode loading and microcode updates must be present early at boot. See Microcode article for more details.

Microcode loading support in kernel

By default, genkernel will enable microcode loading support in kernel for both, AMD and Intel processors. This behavior can be controlled through MICROCODE option in /etc/genkernel.conf or by using the --microcode=(no|all|amd|intel) command-line parameter during invocation.

Embedding microcode updates into initramfs

To embed microcode (ucode) updates into initramfs, MICROCODE_INITRAMFS must be enabled in /etc/genkernel.conf or command-line parameter --microcode-initramfs must be passed at invocation. This will cause genkernel to prepend microcode(s) for selected processor (see --microcode option above) to initramfs in case sys-firmware/intel-microcode with the split-ucode USE flag for Intel processors and/or sys-kernel/linux-firmware for AMD processors is installed.

Note
The technique of embedding microcode updates into the initramfs has been deprecated for modern systems in favor of using bootloaders (like sys-boot/grub) which are capable of loading multiple initramfs files. When using GRUB, or another modern bootloader, it is recommended to install sys-firmware/intel-microcode for Intel and sys-kernel/linux-firmware for AMD processors, both require the initramfs USE flag to be enabled. Let the bootloader load /boot/amd-uc.img and/or /boot/intel-uc.img in addition to genkernel's initramfs. This will enable updating of the CPU microcode independently of kernel/initramfs updates.

Firmware loading

Specific firmware files can be added to genkernel's automatically generated initramfs when listed, with relative paths, in the variable FIRMWARE_FILES in /etc/genkernel.conf. When sys-kernel/genkernel is installed with USE="firmware" it will prefer firmware files from /lib/firmware.

FILE /etc/genkernel.confIncluding firmware in the initramfs
# Add firmware(s) to initramfs
FIRMWARE="yes"
 
# Specify directory to pull from
FIRMWARE_DIR="/lib/firmware"
 
# Specify a comma-separated list of firmware files or directories to include,
# relative to FIRMWARE_DIR.  If empty or unset, the full contents of 
# FIRMWARE_DIR will be included (if FIRMWARE option above is set to YES).
FIRMWARE_FILES="<comma-separated list of firmware files here>"

In case sys-kernel/gentoo-sources is installed with USE="experimental" and the kernel is configured with CONFIG_GENTOO_PRINT_FIRMWARE_INFO=y, the following command gets a comma-separated list of all currently loaded firmware files for the use in the FIRMWARE_FILES variable from /etc/genkernel.conf as illustrated above (the output is just an example):

root #dmesg -t | grep '^Loading firmware*' | sed 's/^Loading\sfirmware:\s//' | echo $(cat) | tr ' ' ','

It is also possible to incorporate the firmware into the kernel image directly, but be aware that CONFIG_EXTRA_FIRMWARE in the kernel configuration file .config (normally found in /usr/src/linux) requires a space-separated list (output example):

root #dmesg -t | grep '^Loading firmware*' | sed 's/^Loading\sfirmware:\s//' | echo $(cat)
Note
Such a list will only be complete if the drivers successfully load all the required firmware(s): In case a driver requires more than one firmware file but fails loading the first one, only this will be listed and thereby other required firmware filenames will be missing. A recommended procedure to find all required firmware files is to compile the respective drivers as modules first, M in the kernel configuration, and to notthe modules in initramfs. The modules will be loaded after switching to the real / (root) directory, where all firmware files will be available from sys-kernel/linux-firmware (and others) under /lib/firmware. When a system boots successfully with this method, running the above command will gather a complete list of the required firmware files. The files can be included in the initramfs (or the kernel itself), allowing for the drivers to be compiled directly into the kernel, * in the kernel configuration, or to include the drivers as kernel modules in the initramfs as well. In both cases loading the modules will be earlier and it will be successful with the availability of the firmware files in the initramfs, which must be loaded alongside the kernel e.g. using GRUB.

Remote rescue shell

genkernel can embed the net-misc/dropbear SSH daemon into the initramfs which will allow fixing certain things on boot remotely when initramfs is at least able to load. The most common used feature will be remote unlock capability for LUKS-encrypted root or swap devices or ZFS volumes.

Pre-requirement for SSH daemon support in initramfs

A authorized_keys file must exist before genkernel will be invoked. By default, genkernel will look for /etc/dropbear/authorized_keys. Command-line argument --ssh-authorized-keys-file=/path/to/custom/authorized_keys or genkernel configuration option SSH_AUTHORIZED_KEYS_FILE can be used to alter default value.

Tip
Create /etc/dropbear/authorized_keys as a symlink to /root/.ssh/authorized_keys for example to keep root access and remote rescue shell access in sync!

Adding SSH support to initramfs

To embed SSH daemon into genkernel's initramfs, run genkernel with --ssh command-line argument or set SSH="yes" in genkernel configuration file. Needless to mention that this feature will require working network at boot. The following example will just (re-)build initramfs with SSH daemon embedded:

root #genkernel --ssh initramfs
Note
By default, genkernel will generate own, dedicated SSH host keys for any missing supported key algorithm for embedded SSH daemon. This will allow to differentiate between real system's SSH daemon and initramfs' SSH daemon. To use host's SSH host keys instead or generate new keys at runtime on each boot use --ssh-host-keys command-line option and see genkernel's man page for more details.

Enabling SSH daemon on boot

Just adding SSH daemon to initramfs is not enough. Because exposing any network service could be a security risk, this feature must be enabled via the kernel command-line argument dosshd! See Configure Network for how to configure network in genkernel.

Remote unlock

There are two possibilities to unlock LUKS-encrypted root and/or swap volume: A manual way, through an SSH connection, run a command and will get prompted for passphrase(s) or an automatic way where user passes passphrase through SSH as command.

Note
This will require a kernel/initramfs generated with --luks command-line argument and kernel must be booted with crypt_root (and/or crypt_swap) kernel command-line argument. ZFS user must generate kernel/initramfs with --zfs command-line argument and kernel must be booted with dozfs kernel command-line argument.
Manual unlock

Connect to the remote system through SSH and run the following commands:

user $ssh root@remote-system-running-genkernel-initramfs-with-dosshd
Note
In this example, system was booted with just crypt_root= set in kernel command-line. In case system was booted with crypt_swap= there will be an additional prompt regarding how to unlock swap. ZFS user will get prompted to use unlock-zfs command instead.
Automatic unlock

It's basically the same like manual unlock just without the need to manually run resume-boot. In case user has both, encrypted root and swap volume, user must unlock swap volume first:

user $cat /path/to/secret.key/on/local/disk | ssh root@remote-system-running-genkernel-initramfs-with-dosshd post root
Note
Automatic unlock is not available for ZFS users.

Network booting

From an installation CD

The genkernel utility can build kernel and initrd images that provide support for network booting, or netbooting. With any luck, users should be able to netboot any recent computer into the environment provided by the Installation CD.

The magic lies in genkernel's linuxrc script: it will try to netmount the Installation CD using NFS. From there, the init scripts of the Installation CD can take over, as if the CD was present locally.

Building the kernel and initramfs with netboot support

To enable support for netbooting, include the following options while configuring the kernel:

Warning
Support for netbooting with genkernel is experimental and may contain bugs.

First, the kernel image must include the drivers for the system's Network Interface Cards (NIC). Normally, drivers for such devices will be compiled as modules. However, it is essential (for netbooting) that such drivers are compiled directly into the kernel image and not as modules.

KERNEL Configuring a 3.x.x series kernel to support various NIC drivers
Device Drivers --->
   Networking Support --->
      Ethernet (10 or 100Mbit)  --->
         [*] Ethernet (10 or 100Mbit)
         <*>   The driver(s) for each network card
Note
Be sure to select <*> and not <M>.

Secondly, it is suggested that IP: kernel level autoconfiguration is enabled as well as IP: DHCP support options. This avoids an unnecessary layer of complexity since the IP address and the NFS path to the Installation CD can be configured on a DHCP server. Of course, this means the kernel command line will remain constant for any machine — which is very important for etherbooting.

KERNEL Configuring a 3.x.x series kernel to support DHCP
Device Drivers --->
   Networking Support --->
      Networking options
         [*] TCP/IP networking--->
         [*]   IP: kernel level autoconfiguration
         [*]     IP: DHCP support

Tells the kernel to send a DHCP request at bootup.

Additionally, enable SquashFS because most modern Gentoo Installation CDs require it. Support for SquashFS is not included with the generic kernel source tree. To enable SquashFS, apply the necessary patches to the generic kernel source or install gentoo-sources.

KERNEL Configuring the kernel to support SquashFS
File systems--->
   Miscellaneous filesystems --->
      [*] SquashFS 2.X - Squashed file system support

Once the compilation process is completed, create a compressed tarball (tar.gz) that contains the kernel's modules. This step is only necessary if the kernel version does not match the kernel image version on the Installation CD.

To create an archive containing all the modules:

root #cd /
root #tar -cf /tmp/modules-X.Y.Z.tar.gz /lib/modules/X.Y.Z/

Depending on the network boot mechanism, one of the following steps need to be followed:

To create an etherboot image:

root #emerge --ask net-misc/mknbi
root #cd /boot
root #mkelf-linux -params="root=/dev/ram0 init=/linuxrc ip=dhcp" kernel... initrd... > etherboot.img

To create an OpenBoot/SPARC64 TFTP image:

root #emerge --ask sys-apps/sparc-utils
root #cd /boot
root #elftoaout kernel... -o kernel.aout
root #piggyback64 kernel.aout System.map-... initrd-...
root #mv kernel.aout openboot.img

The openboot.img file is the boot image.

Finally, copy this kernel to the TFTP server. The details are architecture-dependent and are beyond the scope of this guide. Please refer to the documentation for the specific platform of interest.

NFS setup

To setup a NFS share that contains the Installation CD, use the loop device to mount the ISO image and then copy the contents of the CD into the NFS share. As a nice extra, genkernel's initrd scripts will extract all tar.gz files located in the /nfs/livecd/add/ directory. All that needs to be done here is copy the modules-X.Y.Z.tar.gz archive to the /nfs/livecd/add/ directory.

The following assumes that /nfs/livecd is an exported NFS share:

root #mount /tmp/gentoo-livecd.iso /mnt/cdrom -o loop
root #cp -p /mnt/cdrom /nfs/livecd
root #umount /mnt/cdrom

Now copy the modules.tar.gz file into /add:

root #mkdir /nfs/livecd/add
root #cp /tmp/modules-X.Y.Z.tar.gz /nfs/livecd/add

DHCP setup

The netboot images will ask the DHCP server on the network for an IP as well as a root-path option. Both can be specified per host using a MAC address to identify machines:

FILE /etc/dhcpd.confSample client dhcpd.conf setup
# Here, 192.168.1.2 is the NFS server while 192.168.1.10 will be the IP address of the netbooted machine
host netbootableMachine {
         hardware ethernet 11:22:33:44:55:66;
         fixed-address 192.168.1.10;
         option root-path "192.168.1.2:/nfs/livecd";
}

Netbooting instructions

Netbooting itself is again very platform-specific. The important part is to specify the ip=dhcp and init=/linuxrc parameters on the kernel command line, as this will bring up the network interface and tell the initrd scripts to mount the Installation CD via NFS. Here are some platform-specific tips.

For etherboot, insert the etherboot disk into the drive and reboot. The kernel command line was specified when the image was constructed.

With Sparc64, press Stop+A at the boot prompt and then enter:

okboot net ip=dhcp init=/linuxrc

For PXE, setup pxelinux (part of syslinux), then create a pxelinux.cfg/default along the lines of:

FILE pxelinux.cfg/defaultDefault entry
DEFAULT gentoo
TIMEOUT 40
PROMPT 1
  
LABEL gentoo
    KERNEL kernel-X.Y.Z
    APPEND initrd=initrd-X.Y.Z root=/dev/ram0 init=/linuxrc ip=dhcp

Booting a genkernel initramfs

Introduction

If an initramfs is installed with genkernel, then take a look at the various boot options that can (or should) be defined in the bootloader configuration. The most common ones are added to this guide.

Loading LVM or software-RAID

If the system uses LVM or software-RAID, the initramfs has to be built using the --lvm and --mdadm options. Do not forget to enable support during boot as well. This can be done using the dolvm and domdadm options.

FILE /boot/grub/grub.confEnabling LVM and/or MDADM support
# Example for GRUB 1.x
title Gentoo Linux
root (hd0,0)
kernel /vmlinuz root=/dev/md3 dolvm domdadm
initrd /initramfs-genkernel-x86_64-3.4.3
Booting in single-user mode

If for some reason boot-up fails, rescuing the system by booting in the single-user mode is still possible. This will only load the really necessary services and then drop the user to a rescue (root) shell.

FILE /boot/grub/grub.confBooting in single-user mode
# Example for GRUB 1.x
title Gentoo Linux
root (hd0,0)
kernel /vmlinuz root=/dev/md3 init_opts=S
initrd /initramfs-genkernel-x86_64-3.4.3

Cross-compile support

To build kernel and/or initramfs for a different platform as genkernel is being executed on, kernel/initramfs must be cross-compiled.

root #genkernel --mdadm --no-install --cross-compile=aarch64-linux-gnu all

The above command causes genkernel to create a kernel supporting MD raid and embed mdadm into initramfs (--mdadm), both kernel and initramfs will have to be manually installed (--no-install). The kernel and programs embedded into initramfs will run on arm64 (--cross-compile=aarch64-linux-gnu).

--cross-compile=<target triplet>
Target triple (i.e. aarch64-linux-gnu) to build for. Only needed when the system running genkernel has a different architecture like the system which should boot the created kernel/initramfs.
Tip
The recommended way to create a cross-compile environment is using sys-devel/crossdev. See the how to create a cross-compile environment article for more details.

Initramfs kernel command-line parameters

Note
The following parameter list is just an excerpt. Always check the version relevant man genkernel.
root=<...>
Specifies the device node of the root filesystem to mount. I.e. root=/dev/sda3, root=UUID=a1e5968c-bd1b-41ee-bf08-2d0ed376fa83.
cdroot
This attempts to load livecd.squashfs and is used for loading live media.
crypt_root=<...>
This specifies the device encrypted by LUKS, which contains the root filesystem to mount. Supports same syntax like root kernel command-line parameter from above.
Note
Will require that at least initramfs was built with --luks option set.
crypt_swap=<...>
This specifies the swap device encrypted by LUKS. For more details please see crypt_root kernel command-line parameter from above.
root_trim=(yes|no)
Enables TRIM support for a LUKS-based root device.
Note
Will require that at least initramfs was built with --luks option set and is only useful for flash-based volumes.
ip=<dhcp,addr/cidr>
Normally used to tell the kernel that it should start a network interface which can be specified using gk.net.iface kernel parameter. By default, dhcp will be used. A specific IP address can be set using addr/CIDR notation, i.e. 1.2.3.4/24.
gk.net.dhcp.retries=<...>
Sends up to 3 DHCP discovery requests by default.
gk.net.iface=<interface,macaddr>
Use the interface named eth0 by default. Use this kernel parameter to specify another interface.
A MAC address (00:00:00:00:00:00 format) can be specified instead of an interface name.
gk.net.gw=<...>
Optional gateway. If ip is set to dhcp, this kernel parameter will be ignored.
gk.net.routes=<...>
Optional additional routes. If ip is set to dhcp, this kernel parameter will be ignored.
gk.net.timeout.dad=<...>
Wait up to 10 seconds by default for IPv6's DAD to complete. At the moment, only wait for DAD while bringing down an interface to prevent a race condition.
gk.net.timeout.deconfiguration=<...>
Wait up to 10 seconds by default while bringing down an interface to prevent a race condition.
gk.net.timeout.dhcp=<...>
Wait up to 10 seconds by default for a DHCP server reply.
gk.net.timeout.interface=<...>
Wait up to 10 seconds by default for interface to show up.
gk.prompt.timeout=<...>
By default a prompt within genkernel initramfs like shown when set root could not be found will never timeout. Use this option to set a timeout.
Note
When dosshd is used, gk.prompt.timeout will be set to 30 seconds when not set. This will allow remote user to provide answer through GK_PROMPT_FILE which is set to /tmp/current_prompt by default.
dosshd
Will bring up an interface and start a SSH daemon within initramfs allowing to remotely unlock encrypted devices or just for debugging purpose. See ip option for how to configure network.
Note
Will require that initramfs was built at least with --ssh option set.
gk.sshd.port=<...>
By default, sshd will listen on port 22.
gk.sshd.wait=<...>
Wait X seconds after setting up sshd. Useful for login (and thus pause boot process) before booting real system.
dolvm
Activate LVM volumes on bootup.
Note
Will require that initramfs was built at least with --lvm option set.
lvmraid=<...>
Specify RAID devices to set up before the activation of LVM volumes. Implies option dolvm from above.
domdadm (Deprecated in Genkernel 4.2.0, udev rules now control MD assembly)
Scan for RAID arrays on bootup.
Note
Will require that initramfs was built at least with --mdadm option set.
dozfs[=cache,force]
Scan for bootable ZFS pools on bootup. Optionally use cachefile or force import if necessary or perform both actions.
Note
Will require that initramfs was built at least with --zfs option set.
gk.log.disabled=<...>
By default, any shown message and external command calls will be logged to /tmp/init.log in initramfs. Disables logging.
gk.log.keep=<...>
When set to a boolean value, genkernel will preserve /tmp/init.log, see above, and copy file to /genkernel-boot.log on root device (see root or real_root kernel command-line parameter above). Customize to a file like /root/my-genkernel-boot.log to copy the log.
Note
The default file /genkernel-boot.log on root was chosen because genkernel's initramfs will only mount root filesystem by default. To store the log file at /var/log/genkernel-boot.log, the mount point must be accessible (see /etc/initramfs.mounts).
gk.hw.load-all=<...>
By default, genkernel loads various module groups (nvme, sata, scsi, pata, usb...) until block device specified in root parameter (see above) becomes available. This boolean option can be used to force loading of all module groups regardless whether root device is already available when set to yes.

FAQ

Can genkernel be used for systemd-based systems?

Yes.

Genkernel? Genkernel-next? Dracut?

Note
sys-kernel/genkernel-next has been removed from the Gentoo repository as of August, 20, 2020

Gentoo is about choices. sys-kernel/genkernel-next was created as fork of sys-kernel/genkernel when genkernel development was stuck, booting a systemd-based system using kernel/initramfs created with sys-kernel/genkernel was a problem (systemd support in sys-kernel/genkernel is fixed for quite some time) and some developers wanted support for things like sys-boot/plymouth which requires sys-fs/udev which was not and still is not compatible with genkernel's main idea (see "Note" right at the beginning of this article). While the name suggests that sys-kernel/genkernel-next is or will be the successor of sys-kernel/genkernel, it is just misleading: Since 2013 there are some requests to merge genkernel-next back into genkernel but the process became stuck. Since the release of sys-kernel/genkernel-4 which changed a lot and the fact that there was no progress in sys-kernel/genkernel-next development since 2018, it's now very unlikely that genkernel-next will ever merge back into genkernel.

sys-kernel/dracut in comparison to sys-kernel/genkernel is just a generic tool for creating an initramfs. It does not create a kernel like genkernel does. I.e. while both, genkernel and dracut supports booting from LUKS-encrypted root volume, only genkernel will ensure that kernel will have all required options set. It's also worthwhile to mention that genkernel will compile most packages (LVM, cryptsetup, mdadm, sshd...) used in initramfs on its own whereas dracut will copy binaries from host system which can be a problem for some setups. Thus, genkernel supports kernel/initramfs creation for another system (cross-compile) unlike dracut or genkernel-next.

Can a separate kernel/initramfs be created for tests?

root #genkernel --kernel-config=/proc/config.gz --kernel-append-localversion=-test42 --menuconfig all

The above command causes genkernel to build a new kernel and initramfs (all) based on config from current running kernel (--kernel-config=/proc/config.gz), invoke menuconfig (--menuconfig) allowing user to adjust configuration and will append -test42 to kernel's LOCALVERSION variable (--kernel-append-localversion=-test42) which will affect naming of kernel image, modules dir and initramfs by default.

How can external modules (such as xtables-addons, nvidia-drivers...) be rebuilt for a new kernel?

By default, genkernel will call emerge @module-rebuild when building a kernel to ensure that out-of-tree modules installed through the package manager are still present in new/rebuilt kernel. This feature can be toggled via --[no-]module-rebuild command-line argument or MODULEREBUILD in /etc/genkernel.conf.

How can additional commands be run after building the kernel?

Genkernel provides a callback for that (before version 4, callback was used to rebuild external modules). See CMD_CALLBACK in /etc/genkernel.conf for more details.

How can ccache or distcc be used with genkernel?

Set up ccache or distcc the normal way like for sys-apps/portage. Set --kernel-cc command-line parameter or adjust KERNEL_CC in /etc/genkernel.conf for the desired tool to use. Do the same for UTILS_CC (--utils-cc) and UTILS_CXX (--utils-cxx).

ERROR: compile_kernel(): compile_generic() failed to compile the "bzImage" target!

Check /var/log/genkernel.log first. In most cases, a root cause will appear like:

FILE /var/log/genkernel.log
[...]
  AR      drivers/usb/built-in.a
  AR      drivers/built-in.a
  GEN     .version
  CHK     include/generated/compile.h
  AR      built-in.a
  LD      vmlinux.o
  MODPOST vmlinux.o
ld: .tmp_vmlinux1: final close failed: No space left on device
make: *** [Makefile:1032: vmlinux] Error 1
 
* ERROR: compile_kernel(): compile_generic() failed to compile the "bzImage" target!
* Please consult '/var/log/genkernel.log' for more information and any
* errors that were reported above.
*
* Report any genkernel bugs to bugs.gentoo.org and
* assign your bug to genkernel@gentoo.org. Please include
* as much information as you can in your bug report; attaching
* '/var/log/genkernel.log' so that your issue can be dealt with effectively.
*
* Please do *not* report kernel compilation failures as genkernel bugs!
*
 
* mount: >> Boot partition state on '/boot' was not changed; Skipping restore boot partition state ...
>>> Ended on: 2019-12-16 02:30:19 (after 0 days 0 hours 07 minutes 49 seconds)
</pre>

In other words: The system has run out of disk space (No space left on device) during compilation.

To guard against problems like this set CHECK_FREE_DISK_SPACE_BOOTDIR=50 and CHECK_FREE_DISK_SPACE_KERNELOUTPUTDIR=4000 in /etc/genkernel.conf in which case genkernel would fail early with a message like

root #genkernel --kernel-config=/proc/config.gz all 
* Gentoo Linux Genkernel; Version 4.0.1
* Using genkernel configuration from '/etc/genkernel.conf' ...
* Running with options: --kernel-config=/proc/config.gz all
 
* Working with Linux kernel 4.19.89-gentoo-x86_64 for x86_64
* Using kernel config file '/proc/config.gz' ...
*
* Note: The version above is subject to change (depends on config and status of kernel sources).
* ERROR: 4000 MB free disk space is required in '/usr/src/linux' but only 1026 MB is available!
[...]

Is the order of kernel command-line arguments important?

No.

Required kernel option 'CONFIG_MICROCODE_INTEL' or 'CONFIG_MICROCODE_AMD' which genkernel tried to set is missing!

Kernel v6.6 permanently applied the kernel config parameters (see this commit). This was fixed in version 4.3.10 of sys-kernel/genkernel.

Help! Something isn't working!

To report a problem, please always provide /var/log/genkernel.log (sometimes it maybe necessary to compress that file before sharing or attaching to bugs) which will help developers a lot. Even if the command is run with --loglevel=1 (default), the logfile will always contain complete output (no need to re-run with logging turned on) which will help developers to understand, reproduce and maybe fix a bug.

See also

This page is based on a document formerly found on our main website gentoo.org.
The following people contributed to the original document: Tim Yamin, Jimi Ayodele, Thomas Seiler, Joshua Saddler (nightmorph), Sebastian Pipping (sping) , José Fournier (jaaf)
They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.

Retrieved from "https://wiki.gentoo.org/index.php?title=Genkernel/hu&oldid=1371071"