Home / About / The Way I Work / Gentoo Linux on a Framework Laptop (DIY Edition) 12th Gen

Installation Notes

Gentoo Linux on a Framework Laptop (DIY Edition) 12th Gen

An archive of the steps taken to install and configure Gentoo Linux on a Framework Laptop (DIY Edition) 12th Gen using GNU+Linux. Last updated on 05 May 2026

rob@gloop
---------
OS: Gentoo Linux x86_64
Host: Laptop (12th Gen Intel Core) (A8)
Kernel: Linux 6.18.26-gentoo
Uptime: 46 mins
Packages: 1170 (emerge)
Shell: bash 5.3.9
Display (BOE095F): 2256x1504 @ 1.2x in 13", 60 Hz [Built-in]
WM: dwl (Wayland)
Theme: Adwaita-Dark [Qt], Arc-Dark [GTK2/3/4]
Icons: Boston cardboard [Qt], Blue-Maia [GTK2/3], breeze-dark [GTK4]
Font: Roboto (16pt) [Qt], Sans (16pt) [GTK2/3], Noto Sans (14pt) [GTK4]
Cursor: breeze (24px)
Terminal: foot 1.24.0
Terminal Font: hack (16pt)
CPU: 12th Gen Intel(R) Core(TM) i7-1280P (20) @ 4.80 GHz
GPU: Intel Iris Xe Graphics @ 1.45 GHz [Integrated]
Memory: 4.83 GiB / 62.51 GiB (8%)
Swap: Disabled
Disk (/): 600.45 GiB / 3.58 TiB (16%) - ext4
Battery (FRANGWA): 90% [Charging, AC Connected]
Locale: C.UTF-8




Framework Laptop (DIY Edition) 12th Gen Specs

Framework Laptop (DIY Edition) 12th Gen
Framework Laptop (DIY Edition) 12th Gen
Framework Laptop 13 DIY Edition Quick Start Guide



The Framework Laptop, first released in 2021, is a laptop that focuses on extreme repairability. The DIY edition in particular comes without an OS and the developers and community are currently focused on supporting Arch Linux as an alternative to Windows.
Gentoo Wiki info on Framework Laptops

Installation Notes - Gentoo Linux


PREPARE THE DISK
root # cfdisk /dev/nvme0n1
/dev/nvme0n1p1  /efi 		1G   	EFI
/dev/nvme0n1p2  /boot 		1G   	Extended Boot
/dev/nvme0n1p3	/   		3.6T 	Linux

LOAD THE DM-CRYPT MODULE
root # modprobe dm-crypt
CREATE LUKS VOLUME
root # cryptsetup luksFormat /dev/nvme0n1p3
LUKS HEADER BACKUP
root # cryptsetup luksHeaderBackup /dev/nvme0n1p3 --header-backup-file root_headers.img
OPEN THE LUKS VOLUME
root # cryptsetup luksOpen /dev/nvme0n1p3 root
Enter your password.
Note:
In this example, the volume is opened and mapped to /dev/mapper/root, as suggested by the Discoverable Partitions Specification.

FILESYSTEMS PREPARATION

FORMAT ESP PARTITION
root # mkfs.fat -F 32 /dev/nvme0n1p1
ROOT FILESYSTEM
root # mkfs.ext4 -L rootfs /dev/mapper/root
OPTIONAL: EXTENDED BOOT PARTITION
If used, the extended boot partition must be formatted. Any filesystem which the bootloader supports can be used.

root # mkfs.ext4 -l boot /dev/nvme0n1p2
GENTOO INSTALLATION
At this point the rest of the gentoo handbook applies as normal.

Important
* sys-fs/cryptsetup must be installed within the chroot, before the initramfs is created.

## An initial RAM filesystem must be built with support for decrypting and mounting the root partition.
## If a bootloader is being used, it must be configured and installed on unencrypted volumes.

The root file system can be mounted at /mnt/gentoo to continue the install with: Installing a stage tarball.

SET DATE AND TIME
root # date MMDDhhmmYYYY
Download and install stage3 into /mnt/gentoo Start sshd, set root passwd, create user and passwd

DOWNLOADING THE STAGE TARBALL
root # cd /mnt/gentoo
root # links https://www.gentoo.org/downloads/mirrors/
Move to the releases/amd64/autobuilds/ directory. There all available stage files are displayed (they might be stored within subdirectories named after the individual sub-architectures). Select one and press d to download.

VALIDATE THE DOWNLOAD
root # sha512sum stage3-amd64-.tar.?(bz2|xz)
UNPACK THE DOWNLOAD
root # tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner
CONFIGURING COMPILE OPTIONS
root # nano -w /mnt/gentoo/etc/portage/make.conf
SELECTING MIRRORS
root # mirrorselect -i -o >> /mnt/gentoo/etc/portage/make.conf
Configuring the repository can be done in a few simple steps. First, if it does not exist, create the repos.conf directory:
root # mkdir --parents /mnt/gentoo/etc/portage/repos.conf
Next, copy the Gentoo repository configuration file provided by Portage to the (newly created) repos.conf directory:
root # cp /mnt/gentoo/usr/share/portage/config/repos.conf /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

FILE: /mnt/gentoo/etc/portage/repos.conf/gentoo.conf

[DEFAULT]
main-repo = gentoo
 
[gentoo]
location = /var/db/repos/gentoo
sync-type = rsync
sync-uri = rsync://rsync.gentoo.org/gentoo-portage
auto-sync = yes
sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4
COPY DNS INFO
One thing still remains to be done before entering the new environment and that is copying over the DNS information in /etc/resolv.conf. This needs to be done to ensure that networking still works even after entering the new environment. /etc/resolv.conf contains the name servers for the network.

To copy this information, it is recommended to pass the --dereference option to the cp command. This ensures that, if /etc/resolv.conf is a symbolic link, that the link's target file is copied instead of the symbolic link itself. Otherwise in the new environment the symbolic link would point to a non-existing file (as the link's target is most likely not available inside the new environment).
root # cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
MOUNTING THE NECESSARY FILESYSTEMS
root # mount -t proc /proc /mnt/gentoo/proc
root # mount --rbind /sys /mnt/gentoo/sys
root # mount --make-rslave /mnt/gentoo/sys
root # mount --rbind /dev /mnt/gentoo/dev
root # mount --make-rslave /mnt/gentoo/dev
CHROOTING
root # chroot /mnt/gentoo /bin/bash
root # source /etc/profile
root # export PS1="(chroot) $PS1"
INSTALLING A GENTOO EBUILD REPOSITORY SNAPSHOT FROM THE WEB
root # emerge-webrsync
CHOOSING THE RIGHT PROFILE
root # eselect profile list
Available profile symlink targets:
  [1]   default/linux/amd64/23.0 (stable)
  [2]   default/linux/amd64/23.0/systemd (stable)
  [3]   default/linux/amd64/23.0/desktop (stable) *
  [4]   default/linux/amd64/23.0/desktop/systemd (stable)
  [5]   default/linux/amd64/23.0/desktop/gnome (stable)
  [6]   default/linux/amd64/23.0/desktop/gnome/systemd (stable)
  [7]   default/linux/amd64/23.0/desktop/plasma (stable)
  [8]   default/linux/amd64/23.0/desktop/plasma/systemd (stable)
  [9]   default/linux/amd64/23.0/no-multilib (stable)
  [10]  default/linux/amd64/23.0/no-multilib/systemd (stable)
  [11]  default/linux/amd64/23.0/no-multilib/hardened (stable)
  [12]  default/linux/amd64/23.0/no-multilib/hardened/systemd (stable)
  [13]  default/linux/amd64/23.0/no-multilib/hardened/selinux (stable)
  [14]  default/linux/amd64/23.0/no-multilib/hardened/selinux/systemd (stable)
  [15]  default/linux/amd64/23.0/no-multilib/prefix (exp)
  [16]  default/linux/amd64/23.0/no-multilib/prefix/kernel-2.6.32+ (exp)
  [17]  default/linux/amd64/23.0/no-multilib/prefix/kernel-2.6.16+ (exp)
  [18]  default/linux/amd64/23.0/no-multilib/prefix/kernel-3.2+ (exp)
  [19]  default/linux/amd64/23.0/llvm (exp)
  [20]  default/linux/amd64/23.0/llvm/systemd (exp)
  [21]  default/linux/amd64/23.0/hardened (stable)
  [22]  default/linux/amd64/23.0/hardened/systemd (stable)
  [23]  default/linux/amd64/23.0/hardened/selinux (stable)
  
.....
SELECT A PROFILE
root # eselect profile set 5
SYSTEM UPDATE
Updating the @world set
At this point, it is wise to update the system's @world set so that a base can be established.
root # emerge --ask --verbose --update --deep --newuse @world
TIME
root # echo "America/Chicago" > /etc/timezone
root # emerge --config sys-libs/timezone-data
LOCALE GENERATION
root # nano -w /etc/locale.gen
root # locale-gen
root # env-update && source /etc/profile && export PS1="(chroot) ${PS1}"
INSTALLING FIRMWARE AND/OR MICROCODE
Firmware
Suggested Linux Firmware (Most wireless cards and GPUs require firmware to function.

root # emerge --ask sys-kernel/linux-firmware
Firmware Loading
Firmware files are typically loaded when the associated kernel module is loaded. This means the firmware must be built into the kernel using CONFIG_EXTRA_FIRMWARE if the kernel module is set to Y instead of M. In most cases, building-in a module which required firmware can complicate or break loading.

Microdoce firmware blobs
root # eecho "sys-kernel/linux-firmware @BINARY-REDISTRIBUTABLE" >> /etc/portage/package.license
root # emerge --ask sys-firmware/intel-microcode
SOF Firmware
Sound Open Firmware (SOF) is a new open source audio driver meant to replace the proprietary Smart Sound Technology (SST) audio driver from Intel. 10th gen+ and Apollo Lake (Atom E3900, Celeron N3350, and Pentium N4200) Intel CPUs require this firmware for certain features and certain AMD APUs also have support for this firmware. SOF's supported platforms matrix can be found here for more information.
root # emerge --ask sys-firmware/sof-firmware
INITRAMFS CONFIGURATION
An initramfs must be used to decrypt and mount the root partition. This can be accomplished using an image generated by a tool such as UgRD.

Important:
This configuration should be done while chrooted, or in the system which the initramfs is being built for.

UGRD
Tip:
UGRD (µgRD for Microgram Ramdisk) should automatically detect most LUKS configurations, requiring no additional configuration.

ugrd can be installed directly, but is best installed by adding it as a USE flag for installkernel:
FILE /etc/portage/package.use
sys-kernel/installkernel -dracut ugrd


Once configured, installkernel can be re-emerged and will pull UGRD:
root # emerge -1 sys-kernel/installkernel

INSTALL KERNEL SOURCES
root # emerge --ask sys-kernel/gentoo-sources
root # emerge --ask sys-apps/pciutils

REMINDER
Make sure nm-applet and networkmanager both have use flag "modemmanager"
------------------------------------------------------------------------
Device Drivers  --->
  [*] Multiple devices driver support (RAID and LVM)  --->
    <*>   Device mapper support
    <*>     Crypt target support
-*- Cryptographic API  --->
  <*>   AES cipher algorithms (x86_64)
COMPILING AND INSTALLING
With the configuration now done, it is time to compile and install the kernel. Exit the configuration and start the compilation process:
root # emerge sys-kernel/installkernel

root # make && make modules_install
root # make install

root # emerge cryptsetup

root # rc-update add sshd default
root # rc-update add dmcrypt boot
root # rc-update add lvm boot


root # nano -w /etc/fstab

#fstab
/dev/nvme0n1p1          /efi   	vfat    noauto,noatime,discard  0 2
/dev/nvme0n1p2          /boot   ext4    noauto,noatime,discard  0 2
/dev/mapper/root     	/       ext4    noatime                         0 1
tmpfs                   /tmp    tmpfs   rw,nosuid,noatime,nodev,size=4G,mode=1777 0 0
HOST INFO
root # nano -w /etc/conf.d/hostname
CONFIGURING THE NETWORK
During the Gentoo Linux installation, networking was already configured. However, that was for the installation CD itself and not for the installed environment. Right now, the network configuration is made for the installed Gentoo Linux system.

All networking information is gathered in /etc/conf.d/net. It uses a straightforward yet perhaps not intuitive syntax. But don't fear, everything is explained below. A fully commented example that covers many different configurations is available in /usr/share/doc/netifrc-*/net.example.bz2.

FIRST INSTALL NET-MISC/NETIFRC:
root # emerge --ask --noreplace net-misc/netifrc
DHCP is used by default. For DHCP to work, a DHCP client needs to be installed. This is described later in Installing Necessary System Tools.

If the network connection needs to be configured because of specific DHCP options or because DHCP is not used at all, then open /etc/conf.d/net:
root # nano -w /etc/conf.d/net

FILE /etc/conf.d/net
Static IP definition
------------------------------------------------------------------------
config_eth0="192.168.0.2 netmask 255.255.255.0 brd 192.168.0.255"
routes_eth0="default via 192.168.0.1"

To use DHCP, define config_eth0:
FILE /etc/conf.d/netDHCP definition

config_eth0="dhcp"
AUTOMATICALLY START NETWORKING AT BOOT
To have the network interfaces activated at boot, they need to be added to the default runlevel.
root # cd /etc/init.d
root # ln -s net.lo net.eth0
root # rc-update add net.eth0 default
If the system has several network interfaces, then the appropriate net.* files need to be created just like we did with net.eth0.

If after booting the system we find out that the assumption about the network interface name (which is currently documented as eth0) was wrong, then execute the following steps to rectify this:

Update the /etc/conf.d/net file with the correct interface name (like enp3s0 instead of eth0).
Create new symbolic link (like /etc/init.d/net.enp3s0).
Remove the old symbolic link (rm /etc/init.d/net.eth0).
Add the new one to the default runlevel.
Remove the old one using rc-update del net.eth0 default.

HOSTS FILE
Next inform Linux about the network environment. This is defined in /etc/hosts and helps in resolving host names to IP addresses for hosts that aren't resolved by the nameserver.
root #nano -w /etc/hosts
FILE /etc/hosts
------------------------------------------------------------------------
# This defines the current system and must be set
127.0.0.1     tux.homenetwork tux localhost
  
# Optional definition of extra systems on the network
192.168.0.5   jenny.homenetwork jenny
192.168.0.6   benny.homenetwork benny
ROOT PASSWORD
Set the root password using the passwd command.
root # passwd
INIT AND BOOT CONFIGURATION
Review the settings and change where needed.
root # nano -w /etc/rc.conf
root # nano -w /etc/conf.d/keymaps
root # nano -w /etc/conf.d/hwclock
If the hardware clock is not using UTC, then it is necessary to set clock="local" in the file. Otherwise the system might show clock skew behavior.

SYSTEM LOGGER
root # emerge --ask app-admin/metalog
root # rc-update add metalog default
CRON DAEMON
root # emerge --ask sys-process/cronie
root # rc-update add cronie default
FILE INDEXING
In order to index the file system to provide faster file location capabilities, install sys-apps/mlocate.
root # emerge --ask sys-apps/mlocate
REMOTE ACCESS
To be able to access the system remotely after installation, add the sshd init script to the default runlevel:
root # rc-update add sshd default
FILESYSTEM TOOLS
Depending on the filesystems used, it is necessary to install the required file system utilities (for checking the filesystem integrity, creating additional file systems etc.). Note that tools for managing ext2, ext3, or ext4 filesystems (sys-fs/e2fsprogs) are already installed as a part of the @system set. 

The tools to install if a certain filesystem is used:
-----------------------------------------------------------------------
Filesystem Package
Ext2,3, and 4 --------- sys-fs/e2fsprogs
XFS ------------------- sys-fs/xfsprogs
ReiserFS -------------- sys-fs/reiserfsprogs
JFS ------------------- sys-fs/jfsutils
VFAT (FAT32, ...) ----- sys-fs/dosfstools
INSTALLING A DHCP CLIENT
Gentoo recommends the use of net-misc/dhcpcd although many other DHCP clients are available through the Gentoo repository.

NetworkManger prefers DHCP:
root # emerge --ask net-misc/dhcp
Emerge
A note for UEFI users: When using UEFI capable systems, users will need to ensure GRUB_PLATFORMS="efi-64" is enabled (as it is the case by default). If that is not the case for the setup, GRUB_PLATFORMS="efi-64" will need to be added to the /etc/portage/make.conf file before emerging GRUB2 so that the package will be built with EFI functionality:
root # echo 'GRUB_PLATFORMS="efi-64"' >> /etc/portage/make.conf
root # emerge --ask sys-boot/grub:2
INSTALL
Next, install the necessary GRUB2 files to the /boot/grub/ directory via the grub-install command.
root # grub-install --target=x86_64-efi --efi-directory=/boot
CONFIGURE
Next, generate the GRUB2 configuration based on the user configuration specified in the /etc/default/grub file and /etc/grub.d scripts. In most cases, no configuration is needed by users as GRUB2 will automatically detect which kernel to boot (the highest one available in /boot/) and what the root file system is. It is also possible to append kernel parameters in /etc/default/grub using the GRUB_CMDLINE_LINUX variable. 
FILE: /etc/default/grub
----------------------------------------------------------------------------------------------------------
# Append parameters to the linux kernel command line
GRUB_CMDLINE_LINUX="net.ifnames=0"
GENERATE THE FINAL GRUB2 CONFIGURATION:
root # grub-mkconfig -o /boot/grub/grub.cfg
REBOOT
root # exit
root # cd
root # umount -l /mnt/gentoo/dev{/shm,/pts,}
root # umount -R /mnt/gentoo
root # reboot
AFTER REBOOT
root # useradd -m -G users,wheel,audio -s /bin/bash rob
root # passwd rob
Backlight
root # emerge -av sys-power/acpid
root # rc-update add acpid default
root # emerge -av sys-power/acpilight


lspci Output

00:00.0 Host bridge: Intel Corporation 12th Gen Core Processor Host Bridge/DRAM Registers (rev 02) 00:02.0 VGA compatible controller: Intel Corporation Alder Lake-P Integrated Graphics Controller (rev 0c) 00:04.0 Signal processing controller: Intel Corporation Alder Lake Innovation Platform Framework Processor Participant (rev 02) 00:06.0 PCI bridge: Intel Corporation 12th Gen Core Processor PCI Express x4 Controller #0 (rev 02) 00:07.0 PCI bridge: Intel Corporation Alder Lake-P Thunderbolt 4 PCI Express Root Port #0 (rev 02) 00:07.1 PCI bridge: Intel Corporation Alder Lake-P Thunderbolt 4 PCI Express Root Port #1 (rev 02) 00:07.2 PCI bridge: Intel Corporation Alder Lake-P Thunderbolt 4 PCI Express Root Port #2 (rev 02) 00:07.3 PCI bridge: Intel Corporation Alder Lake-P Thunderbolt 4 PCI Express Root Port #3 (rev 02) 00:08.0 System peripheral: Intel Corporation 12th Gen Core Processor Gaussian & Neural Accelerator (rev 02) 00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) 00:0d.0 USB controller: Intel Corporation Alder Lake-P Thunderbolt 4 USB Controller (rev 02) 00:0d.2 USB controller: Intel Corporation Alder Lake-P Thunderbolt 4 NHI #0 (rev 02) 00:0d.3 USB controller: Intel Corporation Alder Lake-P Thunderbolt 4 NHI #1 (rev 02) 00:14.0 USB controller: Intel Corporation Alder Lake PCH USB 3.2 xHCI Host Controller (rev 01) 00:14.2 RAM memory: Intel Corporation Alder Lake PCH Shared SRAM (rev 01) 00:15.0 Serial bus controller: Intel Corporation Alder Lake PCH Serial IO I2C Controller #0 (rev 01) 00:15.1 Serial bus controller: Intel Corporation Alder Lake PCH Serial IO I2C Controller #1 (rev 01) 00:15.3 Serial bus controller: Intel Corporation Alder Lake PCH Serial IO I2C Controller #3 (rev 01) 00:16.0 Communication controller: Intel Corporation Alder Lake PCH HECI Controller (rev 01) 00:16.3 Serial controller: Intel Corporation Alder Lake AMT SOL Redirection (rev 01) 00:1d.0 PCI bridge: Intel Corporation Device 51b0 (rev 01) 00:1f.0 ISA bridge: Intel Corporation Alder Lake PCH eSPI Controller (rev 01) 00:1f.3 Audio device: Intel Corporation Alder Lake PCH-P High Definition Audio Controller (rev 01) 00:1f.4 SMBus: Intel Corporation Alder Lake PCH-P SMBus Host Controller (rev 01) 00:1f.5 Serial bus controller: Intel Corporation Alder Lake-P PCH SPI Controller (rev 01) 01:00.0 Non-Volatile memory controller: Sandisk Corp WD PC SN810 / Black SN850 NVMe SSD (rev 01) a6:00.0 Network controller: Intel Corporation Wi-Fi 6 AX210/AX211/AX411 160MHz (rev 1a)


make.conf

# These settings were set by the catalyst build script that automatically # built this stage. # Please consult /usr/share/portage/config/make.conf.example for a more # detailed example. #COMMON_FLAGS="-O2 -pipe" COMMON_FLAGS="-march=native -O2 -pipe" CFLAGS="${COMMON_FLAGS}" CXXFLAGS="${COMMON_FLAGS}" FCFLAGS="${COMMON_FLAGS}" FFLAGS="${COMMON_FLAGS}" RUSTFLAGS="${RUSTFLAGS} -C target-cpu=native" # NOTE: This stage was built with the bindist USE flag enabled # This sets the language of build output to English. # Please keep this setting intact when reporting bugs. LC_MESSAGES=C.UTF-8 # NOTE: This stage was built with the bindist Use flag enabled PORTDIR="/var/db/repos/gentoo" DISTDIR="/var/cache/distfiles" PKGDIR="/var/cache/binpkgs" # NOTE: This stage was built with the bindist Use flag enabled # # Using a large number of jobs can significantly impact memory consumption. \ # A good recommendation is to have at least 2 GiB of RAM for every job \ # specified (so, e.g. -j6 requires at least 12 GiB). To avoid running out of \ # memory, lower the number of jobs to fit the available memory. MAKEOPTS="-j15" CHOST="x86_64-pc-linux-gnu" VIDEO_CARDS="intel" INPUT_DEVICES="synaptics libinput wacom mouse keyboard" # USE="device-mapper initramfs lvm lvm2 -consolekit -systemd -gnome -qt4 -qt5 -kde -obex -ldap dbus alsa-plugin bluetooth elogind gtk xinerama pulseaudio networkmanager \ alsa X xft vaapi vulkan wayland egl gles2 opengl thunderbolt icu" # wayland egl gles2 L10N=" en en-US" # GRUB_PLATFORMS="efi-64" SANE_BACKENDS="epson2" GENTOO_MIRRORS="https://mirrors.mit.edu/gentoo-distfiles/ \ https://gentoo.osuosl.org/ \ https://mirrors.rit.edu/gentoo/ \ http://mirrors.rit.edu/gentoo/ \ https://mirror.umd.edu/gentoo/ \ http://mirror.umd.edu/gentoo/"


Kernel Config

Here is my config file for kernel-config-6.18.26-gentoo