From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Bcachefs is a fully-featured filesystem based on bcache. With features such as Copy-on-Write, compression and encryption bcachefs is comparable to btrfs and zfs.

A noteworthy feature is native tiered storage support, enabling use of one or more fast disk drives (such as flash-based solid state drives or NVMe disks) to act as a cache for one or more slower disk drives in a pool while transparently managing 'hot' and 'cold' files based on activity.

User documentation is available here.

As of November 2022, upstream considers this file system to be 'beta quality'. While there are users in the wild and no widespread reports of data loss, there is some risk. Here be dragons; proceed with the risks in mind, and backup frequently!


While the bcachefs developers are working towards mainlining the filesystem, as of November 2022 the easiest way to try bcachefs is to check out the bcachefs sources and build a new kernel.

user $cd bcachefs
user $cat /proc/config.gz | gunzip > .config

An alternative to this is to get a copy of a bcachefs patch from a patchset such as linux-tkg and apply it to the system kernel as a user patch.

Kernel configuration

Activate the following kernel options:

KERNEL bcachefs filesystem support (BCACHEFS_FS)
File Systems --->
   <*> bcachefs filesystem support
If the crc32c-intel module is available and bcachefs loads before it (or is built in) the CRC32 hardware instruction will not be used resulting in increased system resource utilisation. Ensure that the module loads before bcachefs or build it into the kernel to avoid this.

Additional software

Install sys-fs/bcachefs-tools:

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


To format and use a single filesystem with bcachefs:

root #bcachefs format /dev/sda1
root #mount -t bcachefs /dev/sda1 /mnt

For a multi device filesystem, with sda caching sdb:

root #bcachefs format /dev/sd[ab] --foreground_target /dev/sda --promote_target /dev/sda --background_target /dev/sdb --metadata_target /dev/sda
root #mount -t bcachefs /dev/sda:/dev/sdb /mnt

Advanced usage

Bcachefs supports a a number of additional features, including compression, encryption, and disk labels; an example configuration using these features may be found below:

root #bcachefs format --compression=zstd \
    --encrypted \
    --replicas=2 \
    --label=hdd.hdd1 /dev/sdc \
    --label=hdd.hdd2 /dev/sdd \
    --label=hdd.hdd3 /dev/sde \
    --label=hdd.hdd4 /dev/sdf \
    --label=hdd.hdd5 /dev/sdg \
    --label=hdd.hdd6 /dev/sdh \
    --label=hdd.hdd7 /dev/sdi \
    --label=hdd.hdd8 /dev/sdj \
    --label=hdd.hdd9 /dev/sdk \
    --label=ssd.ssd1 /dev/sdl \
    --label=ssd.ssd2 /dev/sdm \
    --label=ssd.ssd3 /dev/sdn \
    --label=ssd.ssd4 /dev/sdo \
    --label=ssd.ssd5 /dev/sdp \
    --label=ssd.ssd6 /dev/sdq \
    --foreground_target=ssd \
    --promote_target=ssd \
    --background_target=hdd \

Disk decryption

The simplest way to decrypt a bcachefs volume (or pool) is to use the following command on a single member:

root #bcachefs unlock /dev/sdx

To decrypt a bcachefs volume while using systemd, insert '-k session' into the unlock command:

root #bcachefs unlock -k session /dev/sdx

Labels and target options

By default, bcachefs stripes writes across all devices in a filesystem. For more control over the placement of data (or to improve performance) it is possible to direct particular filesystem activity to a disk or collection of disks using labels.

In bcachefs these activities are categorised as target options. Four target options exist which may be set at the filesystem level (at format time, at mount time, or at runtime via sysfs), or on a particular file or directory:

  • foreground target: normal foreground data writes, and metadata if metadata target is not set
  • metadata target: btree writes
  • background target: If set, user data (not metadata) will be moved to this target in the background
  • promote target: If set, a cached copy will be added to this target on read, if none exists

Label names are arbitrary - ssd.ssd1 works just as well as ssd.1 or fast.1. Labels are also hierarchical: to refer to all disks labelled ssd.ssd#, ssd may be used. Labels are not required and it is possible to target to a device directly (e.g. /dev/sda1) however this is not recommended; udev naming is not reliable. In larger pools it is advised to instead use a label for any target that needs to be configured.

Target options may be set as file attributes (i.e. controlled per-file). The bcachefs setattr command is used for this, e.g.:

root #bcachefs setattr --background_target=ssd /path/to/file

See also

  • bcache - a Linux kernel block layer cache.