Introduction

Warning

This is an unofficial documentation collection. See libreboot.org for official information.

Libreboot is libre boot firmware that replaces the proprietary BIOS or UEFI firmware on supported motherboards. Libreboot composes two things:

coreboot: Hardware initialisation, while minimising unwanted vendor functionality (e.g. neutralising the Intel Management Engine where present).
A payload: Runs after coreboot. Libreboot ships SeaBIOS, GRUB, and U-Boot as options, depending on the board. Usually loads your operating system’s bootloader, to then load your operating system’s kernel.

Not a fork of coreboot

Libreboot is a coreboot distribution, in the same way that Alpine Linux is a Linux distribution. Libreboot makes coreboot accessible and easy to use for non-technical users by providing a fully automated build system and user-friendly installation instructions along with regular binary releases with pre-compiled ROM images. Building regular coreboot without Libreboot’s automated build system requires significantly more technical knowledge.

Where to start

You want to install Libreboot on hardware you already own.: Find your board under Targets. Each board page tells you exactly what steps apply to it.
You want hardware with Libreboot already on it.: Minifree sells supported machines preinstalled, and operates a paid install service. Minifree is run by Libreboot’s lead developer; sales fund the project.
You want to know what is and isn’t free software in Libreboot.: See freedom status and the binary blob policy.
You have a question.: The FAQ covers common ones. For anything else, #libreboot on Libera.Chat is where development and user support happen.

FAQ

For installing or troubleshooting a specific board, see Targets. For the freedom status of a given board, see Freedom. This page covers questions that don’t fit neatly into either.

General

How do I install Libreboot?

Find your board under Targets. Each board page covers exactly the steps that apply to it.

How can I help?

See Contributing. Reporting bugs and testing release candidates on hardware you own is useful and doesn’t require deep firmware experience.

Can my motherboard be ported to Libreboot?

Any motherboard supported by coreboot can be ported. The current set is listed under Targets.

Specific board issues

`thinkpad_acpi` fails to load on post-Haswell ThinkPads

On the T440p, W541, and T480 / T480s, modprobe thinkpad_acpi may fail with:

modprobe: ERROR: could not insert 'thinkpad_acpi': "No such device"

Without the module, temperature reporting, battery info, and fan speed reporting/control may not work.

To force-load the module, add

options thinkpad_acpi force_load=1

to a file in /etc/modprobe.d/, or pass thinkpad_acpi.force_load=1 on the kernel command line.

On the T480 specifically, force-loading may turn off rfkill (you will have to manually unblock wlan) and Fn keys F9–F12 may stop working.

Battery monitoring with TLP

Install the tlp package and enable the service. On Debian:

apt-get install tlp tlp-rdw
systemctl enable --now tlp

Then tlp-stat -b (as root) shows battery details. See man tlp-stat for everything else.

Uneven backlight on GM45 ThinkPads

There is no reliable way to detect the correct PWM value in coreboot, so the default is used. This produces uneven backlight on some CCFL panels, but not on LED panels. Workaround: adjust backlight from your distribution.

GM45 ThinkPad ethernet doesn’t autoconnect

This happens on the original BIOS as well; it’s a hardware quirk. With NetworkManager, restarting the service when the cable is plugged in is the usual workaround:

sudo systemctl restart NetworkManager

PIKE2008 module hangs KCMA-D8 / KGPE-D16

Loading the option ROM from the PIKE2008 module hangs the system at boot. Workarounds: use the module from a Linux kernel payload (e.g. LinuxBoot), or boot from regular SATA via SeaGRUB / SeaBIOS and then let Linux drive the PIKE2008 module; Linux can use it without loading the option ROM.

Capturing kernel panic logs over the network

Use the kernel’s netconsole from a second machine. The panicking machine is the source; the machine receiving logs is the target. The source must be on ethernet and the target reachable when the panic happens.

On the target, start a UDP listener:

nc -u -l -p 6666

On the source (as root), mount configfs if it isn’t already:

modprobe configfs
mkdir -p /sys/kernel/config
mount none -t configfs /sys/kernel/config

Find the source ethernet interface (ip address) and the target’s IPv4 address, then set up the netconsole target:

iface=enp0s29f8u1     # change me
tgtip=192.168.1.2     # change me

modprobe netconsole
cd /sys/kernel/config/netconsole
mkdir target1 && cd target1
srcip=$(ip -4 addr show dev "$iface" | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+')
echo "$srcip" > local_ip
echo "$tgtip" > remote_ip
echo "$iface" > dev_name
arping -I "$iface" "$tgtip" -f | grep -o '..:..:..:..:..:..' > remote_mac
echo 1 > enabled
dmesg -n debug

Plug a USB device into the source for a test; log lines should appear in the netcat output on the target. Then reproduce the panic.

Flashing

What does a flash chip look like?

See Identifying the flash chip.

How do I program an SPI flash chip?

See External SPI flashing.

Can I use a CH341A programmer?

Not without modifying it. See Don’t use CH341A.

`flashprog` complains about `/dev/mem` access

Reboot with iomem=relaxed on the kernel command line, or use a kernel without CONFIG_STRICT_DEVMEM. On NetBSD/OpenBSD, the equivalent is kern.securelevel=-1. See Internal flashing for details.

How do I pad a ROM before flashing?

It is usually better to use a ROM image that already matches the flash chip size. If you must pad:

Create a zeroed file of the size difference. To pad a 2 MiB image to fit a 16 MiB chip:

truncate -s 14MiB pad.bin

For x86 descriptorless images, pad before the ROM:

cat pad.bin yourrom.rom > yourrom.rom.new

For ARM and x86 with an Intel Flash Descriptor, pad after the ROM:

cat yourrom.rom pad.bin > yourrom.rom.new

cbfstool cannot operate on padded images, so apply all CBFS changes before padding.

To remove padding (e.g. after dumping a flash chip to operate on it with cbfstool), use dd. To extract a 2 MiB descriptorless ROM from a padded 16 MiB image:

dd if=dump.bin of=yourrom.rom ibs=14MiB skip=1

Configuration

How do I change BIOS settings?

Most settings you’d find in a vendor BIOS setup screen don’t exist on Libreboot; coreboot is configured at build time, not interactively. Some runtime configuration options live in the CMOS table and can be set with nvramtool (in coreboot/util/nvramtool/):

nvramtool -C yourrom.rom -a              # list available options
nvramtool -C yourrom.rom -w name=value   # change one

This modifies the ROM image; you then re-flash it.

In practice, you don’t need to change anything in most cases.

How do I write-protect the flash chip?

By default Libreboot leaves the flash unprotected so users can update it without external programmers. On supported boards you can lock the flash read-only at the OS level, with external flashing still possible. See GRUB hardening.

Do I need to install a bootloader on disk?

If you’re using a Libreboot image with the GRUB payload, no; GRUB is already in the flash chip and will boot your OS directly. You can even remove the disk and still boot a USB installer.

If you’re using SeaBIOS, yes; it expects a normal MBR bootloader on disk, the same as proprietary firmware would.

If you’re using U-Boot, you probably know what you’re doing.

Do I need to re-flash when I reinstall my OS?

No. With the GRUB payload, Libreboot’s GRUB will pick up a grub.cfg on disk if one exists and chainload it. You can also load configs from a USB drive. If you want to override the default, see Modifying grub.cfg in CBFS.

With SeaBIOS, this question doesn’t really apply, it just runs whatever bootloader is on disk.

If you’re using U-Boot, you probably know what you’re doing.

Download

Some ROMs may need to be prepared before flashing. Refer to board-specific documentation.

GPG signing keys

Libreboot releases are signed with GnuPG. Newest keys go first.

First release	Fingerprint
20241206	`8BB1 F7D2 8CF7 696D BF4F 7192 5C65 4067 D383 B1FF`
20160907	`98CC DDF8 E560 47F4 75C0 44BD D0C6 2464 FA8B 4856`
20160818	`CDC9 CAE3 2CB4 B7FC 84FD C804 969A 9795 05E8 C5B2`

HTTP(S) mirrors

Location	URL
Essex, UK	https://rsync.libreboot.org/
Princeton, US	https://mirror.math.princeton.edu/pub/libreboot/
shapovalov, UA	https://mirror.shapovalov.website/libreboot/
Kent, UK	https://www.mirrorservice.org/sites/libreboot.org/release/
MIT, US	https://mirrors.mit.edu/libreboot/
koddos, NL	https://mirror.koddos.net/libreboot/
koddos, HK	https://mirror-hk.koddos.net/libreboot/
cyberbits, FR	https://mirror.cyberbits.eu/libreboot/
cicku, CA	https://ca.mirrors.cicku.me/libreboot/
cicku, AU	https://au.mirrors.cicku.me/libreboot/
cicku, IN	https://in.mirrors.cicku.me/libreboot/
cicku, ZA	https://za.mirrors.cicku.me/libreboot/
diyarciftci, DE	https://mirror.diyarciftci.xyz/libreboot/
diyarciftci, Tor	http://5gxsihf4vjdhimiotrhchihrfujoanondrplizofwparrtmgbwsafhid.onion/libreboot/
diyarciftci, I2P	http://iue4ubnjvskey5gop7n3odkylyjvelb5sl7z4cx6xjwdnthv2hba.b32.i2p/libreboot/

rsync mirrors

Location	URL
Kent, UK	rsync://rsync.mirrorservice.org/libreboot.org/release/
Princeton, USA	rsync://mirror.math.princeton.edu/pub/libreboot/
shapovalov, UA	rsync://rsync.shapovalov.website/libreboot/
linux.ro, RO	rsync://ftp.linux.ro/libreboot/
koddos, NL	rsync://mirror.koddos.net/libreboot/
koddos, HK	rsync://mirror-hk.koddos.net/libreboot/
diyarciftci, DE	rsync://mirror.diyarciftci.xyz/libreboot/