User:Csfore/Bcachefs rootfs

From Gentoo Wiki
Jump to:navigation Jump to:search
Even though this page is in the user namespace, corrections and additions are much appreciated! This is simply wiki policy, this page can be moved to the main wiki as soon as it achieves critical mass more.
bcachefs support is currently in its experimental stages in Gentoo and the Kernel so dragons beware! Please report Kernel issues upstream.
This article has some todo items:
  • Encrypted root (using LUKS and native?)

This article is focused on using bcachefs as the root file system on Gentoo and is intended to be followed alongside the Handbook.

Do not move this article into the main namespace until there is an official LiveCD from RelEng that includes the bcachefs module.

Live Media

Currently, there is no LiveCD available with Bcachefs as a Kernel module so creating a custom boot media with Catalyst will be required, the guide can be found here.

There is a stable version of sys-fs/bcachefs-tools now, but using the latest version may result in the best experience

The changes required to Catalyst's spec files for this guide are:

  • sys-fs/bcachefs-tools in the package list in the stage1 spec file
  • =sys-kernel/gentoo-sources-6.8.1 and sys-fs/bcachefs-tools in the package.accept_keywords used by Catalyst
  • In the stage2 spec file, add livecd/gk_mainargs: --no-microcode (6.7 changes how the microcode config works)
  • A Kernel config in the stage2 file with bcachefs enabled

Disk setup

Grub does not currently have a bcachefs driver, although a bug is opened, so having a unified /boot is required (or a /boot on a different partition)

Before proceeding, follow the handbook and resume this guide after reaching Applying a filesystem to a partition.

The disk layout for bcachefs is similar to a normal disk layout using ext4 or XFS: a vfat boot partition, a swap partition, and the bcachefs partition.

root #mkfs.vfat -F 32 /dev/sda1
root #mkswap /dev/sda2
root #mkfs.bcachefs /dev/sda3

Or, using bcachefs's cli tools:

root #bcachefs format /dev/sda3


Subvolumes in bcachefs are similar to those in btrfs, but with one benefit: they don't need to be mounted! When the root file system is mounted, the subvolumes are mounted along with it.

To create a subvolume for /home, run the following:

root /mnt/gentoo #bcachefs subvolume create home
Listing subvolumes is still a work in progress so for now, verifying the subvolumes exist will not be possible.

Continue following the Handbook and return upon reaching Configuring the Linux kernel

Kernel Config

During my experience, I found it much more convenient to take a dist kernel .config and make olddefconfig to speed up the process. This will likely require an initramfs, however, as the dist kernel uses one unless you wish to find the configs you need to flip to built-in. (Remove this note when moving to the main namespace)

The Kernel package used in this guide is sys-kernel/gentoo-sources, which will need to go into /etc/portage/package.accept_keywords for 6.7.0.

For configuring the kernel, following the manual configuration guide in the Handbook should be sufficient, all that needs to be changed for Bcachefs is:

KERNEL Adding Bcachefs support
File Systems --->
   <*> bcachefs filesystem support (EXPERIMENTAL)
      [ ]   bcachefs quota support
      [ ]   bcachefs erasure coding (RAID5/6) support (EXPERIMENTAL)
      [*]   bcachefs POSIX ACL support
      [ ]   bcachefs runtime info
      [ ]   bcachefs debugging
      [ ]   bcachefs unit and performance tests
      [ ]   bcachefs lock time statistics
      [ ]   disable latency accounting and time stats

If a lscpu shows ssse3 and/or avx2 it is recommended to enable also:

KERNEL Adding Bcachefs support - Accelerated Cryptographic Algorithms
-*- Cryptographic API  --->
    Accelerated Cryptographic Algorithms for CPU (x86)  --->
        [*] Ciphers: ChaCha20, XChaCha20, XChaCha12 (SSSE3/AVX2/AVX-512VL)
        [*] Hash functions: Poly1305 (SSE2/AVX2)
        [*] Hash functions: SHA-224 and SHA-256 (SSSE3/AVX/AVX2/SHA-NI)
        [*] CRC32c (SSE4.2/PCLMULQDQ)

After building the Kernel, if the Distribution Kernel config was used, install the initramfs with

Using sys-kernel/gentoo-sources should automatically run dracut after make install but just in case it doesn't, these instructions should help.
root #dracut --kver=6.7.0-gentoo


An example fstab for a bcachefs rootfs looks like:

FILE /etc/fstab
/dev/sda1 /boot vfat     defaults 1 2
/dev/sda2 none  swap     sw       0 0
/dev/sda3 /     bcachefs defaults 0 0
Dracut will fail to boot if you have fs_passno in your fstab (the second number in 0 0 columns) set to >0 due to it thinking the file system is ext4, set it to 0 in the meantime. (There is a dracut hook but this guide has not tested it yet.)

and finally finish the Handbook, resuming at configuring the system.

Userspace Tools

Installing these tools for Bcachefs on root are required!

To manage Bcachefs in userspace, the package sys-fs/bcachefs-tools will need to be installed.

root #emerge --ask sys-fs/bcachefs-tools

Tested configurations

Remove section when moving to main namespace

The following configurations have been tested and verified:


  • GRUB with unified /boot
  • systemd-boot with unified /boot

Encrypted root

Needs testing.


Does not work.


Multi Device Root FS

Using the command to add a second partition to one bcachefs pool currently leaves the system unbootable when used on the rootfs, so should not be used until bcachefs support is added to sys-boot/grub and other bootloaders. This will work fine if you have the rootfs on one pool and create a second pool which uses multiple partitions.

To tracker this bug please follow this bug report.

This could be worked around by creating your own custom initramfs however this will need a lot of management on the user's part over the lifetime of the system.